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

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

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

{gflow_cli-0.67.0 → 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

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.67.0 → gflow_cli-0.68.0}/AGENTS.md

@@ -43,8 +43,8 @@ by construction, so Codex / Cursor / Aider / `agy` read exactly what Claude Code
 
 - 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)

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

@@ -7,6 +7,60 @@ 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
@@ -3880,7 +3934,8 @@ 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.67.0...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

{gflow_cli-0.67.0 → 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.67.0 → 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.67.0 → gflow_cli-0.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.67.0
+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

{gflow_cli-0.67.0 → 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

{gflow_cli-0.67.0 → 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.

{gflow_cli-0.67.0/website → gflow_cli-0.68.0}/docs/ARCHITECTURE.md

@@ -118,7 +118,8 @@ When the project converges on the hexagonal target above, modules graduate to la
 > `chain*.py`, `composition.py`, `config.py`, `diagnostics.py`, `errors.py`,
 > `image_batch.py`, `json_output.py`, `media.py`, `movie_manifest.py`,
 > `observability.py`, `paths.py`, `profile_lease.py`, `profile_store.py`,
-> `storage.py`, `update_check.py`, and `winsec.py` (inventory refreshed for
+> `storage.py`, `update_check.py` (the once-a-day notice and `gflow update`'s
+> `run_update`; its Click surface is `cli_update.py`), and `winsec.py` (inventory refreshed for
 > v0.56.0, #507 — it had drifted a dozen modules behind).
 > The DDD layout below was deferred indefinitely; converge toward it incrementally
 > if/when a second `Provider` justifies the split (`gflow serve` shipped as a

{gflow_cli-0.67.0 → gflow_cli-0.68.0}/docs/AUTHENTICATION.md

@@ -391,7 +391,7 @@ but the installed Playwright bundled Chromium is older (149.x). ...
 ```
 
 Remedies: upgrade so the bundled Chromium is at least the profile's version
-(`uv tool upgrade gflow-cli`, then `playwright install chromium`), or re-create
+(`gflow update`, then `playwright install chromium`), or re-create
 the profile with `gflow auth login` — login is deliberately *not* guarded, it
 re-mints the session and rewrites the profile, making it the recovery path.
 The guard is best-effort: profiles under the `chrome` strategy (real Google

{gflow_cli-0.67.0 → gflow_cli-0.68.0}/docs/CONFIGURATION.md

@@ -274,10 +274,11 @@ GFLOW_CLI_AUTH_LOGIN_TIMEOUT=120 gflow auth login   # abort after 2 minutes
 
 ### `GFLOW_CLI_UPDATE_CHECK`
 
-**What:** Once-a-day best-effort PyPI check that prints a one-line stderr notice when a newer gflow-cli exists. The notice is always served from a local cache (`<GFLOW_CLI_HOME>/update_check.json`); a stale cache refreshes on a background daemon thread whose result feeds the *next* invocation — the check never blocks or fails a command, and a failed poll still counts toward the once-a-day cap.
+**What:** Once-a-day best-effort PyPI check that shows an update banner on stderr when a newer gflow-cli exists — a bordered panel with the new version, `gflow update`, and the release-notes link when stderr is a terminal; one plain yellow line when piped. The notice is always served from a local cache (`<GFLOW_CLI_HOME>/update_check.json`); a stale cache refreshes on a background daemon thread whose result feeds the *next* invocation — the check never blocks or fails a command, and a failed poll still counts toward the once-a-day cap. `gflow update` / `gflow update --check` refresh the same cache synchronously.
 **Values:** `1` (default) | `0` to disable
-**Skipped automatically:** in CI (`CI` env var set) and for editable/local-source installs (PEP 610 `direct_url.json` detection) — "upgrade" advice is wrong there.
-**Shipped in:** #479.
+**Skipped automatically:** in CI (`CI` set to anything but `0` / `false`) and for editable/local-source installs (PEP 610 `direct_url.json` detection) — "upgrade" advice is wrong there.
+**Upgrading:** [`gflow update`](USAGE.md#gflow-update) runs the installer that put gflow-cli here (`uv tool` / `pipx` / the venv's own `pip`).
+**Shipped in:** #479 (notice); `gflow update` + banner in #668.
 
 ### `GFLOW_CLI_LEASE_WAIT_SECONDS`
 

{gflow_cli-0.67.0/website → gflow_cli-0.68.0}/docs/DEVELOPMENT.md

@@ -63,13 +63,18 @@ Types mirror Conventional Commits: `feature`, `fix`, `docs`, `chore`, `refactor`
 
 ```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
 uv run python -m pytest -q --cov=gflow_cli
 ```
 
-CI runs the same five on every push. Do not bypass with `--no-verify`.
+CI runs the same nine on every push (this list is kept identical to AGENTS.md's —
+`/gflow:check` runs it plus the CLI↔MCP mirror sweep). Do not bypass with `--no-verify`.
 Project pytest defaults exclude `e2e` and `live`; run those credit-spending
 tests only with an explicit marker expression and profile/env setup.
 Local agents running inside an MCP/context sandbox may need to split the

{gflow_cli-0.67.0 → gflow_cli-0.68.0}/docs/INDEX.md

@@ -19,7 +19,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | [KNOWN_ISSUES](../KNOWN_ISSUES.md) | Open / mitigated / resolved issues with workarounds | Before opening a bug report; when something feels off |
 | [DISCLAIMER](../DISCLAIMER.md) | Legal scope, takedown policy, prohibited uses | Before deploying anywhere non-trivial |
 | [LICENSE](../LICENSE) | MIT license text | Always |
-| [CONTRIBUTING](../CONTRIBUTING.md) | TDD workflow, test categories, coverage targets | Before opening a PR |
+| [CONTRIBUTING](../CONTRIBUTING.md) | 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](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](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](AGENT_UI_E2E.md)** | Deterministic e2e runbook for the Agentic UI image path (force-agent trigger, validation ledger) | Live-verifying Agentic-UI features |
@@ -144,7 +144,8 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"What's the standard way to import gflow errors in my code?"** → [USAGE § Programmatic use](USAGE.md#programmatic-use)
 **"gflow refuses to open my profile after a downgrade (exit 11, 'written by a newer Chromium')"** → [AUTHENTICATION § Chromium downgrade guard](AUTHENTICATION.md#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](CONFIGURATION.md#gflow_cli_lease_wait_seconds) (v0.56.0 opt-in bounded wait)
-**"How do I silence the 'newer version on PyPI' stderr notice?"** → [CONFIGURATION § GFLOW_CLI_UPDATE_CHECK](CONFIGURATION.md#gflow_cli_update_check) (`0` disables; auto-skipped in CI and for editable installs)
+**"How do I silence the 'newer version on PyPI' stderr banner?"** → [CONFIGURATION § GFLOW_CLI_UPDATE_CHECK](CONFIGURATION.md#gflow_cli_update_check) (`0` disables; auto-skipped in CI and for editable installs)
+**"How do I upgrade gflow-cli?"** → [USAGE § `gflow update`](USAGE.md#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](CONFIGURATION.md#gflow_mcp_no_spend) + [MCP § Option A2](MCP.md#option-a2-read-only-server) (`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](CONFIGURATION.md#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](CONFIGURATION.md#gflow_cli_flow_host) (`auto` = flow.google.com for every request it can serve — `t2v` with `--project`, on moved and unmoved accounts; `flow.google.com` forces it; `labs.google` is the kill switch. On a moved account everything except `t2v` exits 36, non-retryable, and `t2v` without `--project` exits 11) · recon: [migrated-host wire protocol](superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md), [handoff mechanism](superpowers/spikes/2026-09-04-migrated-host-handoff-mechanism.md) · evidence: [LIVE_VERIFICATION_v0.67.0](LIVE_VERIFICATION_v0.67.0.md)
@@ -156,13 +157,14 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A command failed — where is the incident bundle and what's in it?"** → [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) (layout, triggers, review-before-sharing); privacy boundaries: [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on); disable via [CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE](CONFIGURATION.md#gflow_cli_incident_capture)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.67.0](LIVE_VERIFICATION_v0.67.0.md) (the migrated `flow.google.com` driver — see its own row below) · previous: [LIVE_VERIFICATION_v0.64.0](LIVE_VERIFICATION_v0.64.0.md) (**#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](https://github.com/ffroliva/gflow-cli/issues/561), pre-existing, so verification was stopped rather than spending further credits on an environmental fault.) · previous: [LIVE_VERIFICATION_v0.63.0](LIVE_VERIFICATION_v0.63.0.md) (**`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](LIVE_VERIFICATION_v0.62.1.md) (**#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](LIVE_VERIFICATION_v0.62.0.md) (**#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 `null`s, 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](LIVE_VERIFICATION_v0.61.0.md) (**#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](LIVE_VERIFICATION_v0.60.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.68.0](LIVE_VERIFICATION_v0.68.0.md) (`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](LIVE_VERIFICATION_v0.67.0.md) (the migrated `flow.google.com` driver — see its own row below) · previous: [LIVE_VERIFICATION_v0.64.0](LIVE_VERIFICATION_v0.64.0.md) (**#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](https://github.com/ffroliva/gflow-cli/issues/561), pre-existing, so verification was stopped rather than spending further credits on an environmental fault.) · previous: [LIVE_VERIFICATION_v0.63.0](LIVE_VERIFICATION_v0.63.0.md) (**`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](LIVE_VERIFICATION_v0.62.1.md) (**#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](LIVE_VERIFICATION_v0.62.0.md) (**#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 `null`s, 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](LIVE_VERIFICATION_v0.61.0.md) (**#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](LIVE_VERIFICATION_v0.60.0.md)
 **"Was the playwright upper bound raised, and on what evidence?"** → [LIVE_VERIFICATION_playwright_1.61](LIVE_VERIFICATION_playwright_1.61.md) (**`>=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](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships. Pre-capture research recons: [ASSET_TAGGING_RECON](ASSET_TAGGING_RECON.md) (`@`-mention asset tagging — shipped in v0.40.0, see [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md)).
 **"What was live-verified for v0.66.1?"** → [LIVE_VERIFICATION_v0.66.1](LIVE_VERIFICATION_v0.66.1.md) — **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](LIVE_VERIFICATION_v0.66.0.md) — **#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](https://github.com/ffroliva/gflow-cli/issues/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](LIVE_VERIFICATION_v0.68.0.md) — **`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](LIVE_VERIFICATION_v0.67.0.md) — **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](LIVE_VERIFICATION_v0.66.3.md) — 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.
 

{gflow_cli-0.67.0 → gflow_cli-0.68.0}/docs/LIVE_VERIFICATION_v0.67.0.md

@@ -102,8 +102,11 @@ control … 0 option groups"); fixed in the same change and pinned by
 
 ## Post-tag evidence
 
-Filled after the tag push: release workflow run, PyPI version, GitHub Release URL,
-`pip install gflow-cli==0.67.0` smoke.
+- Signed tag `v0.67.0` (SSH signature, `git tag -v` good) on `f92978e`, pushed 2026-09-05.
+- Release workflow run [33955032750](https://github.com/ffroliva/gflow-cli/actions/runs/33955032750) — `completed / success`.
+- GitHub Release: <https://github.com/ffroliva/gflow-cli/releases/tag/v0.67.0> (published 2026-09-05T08:22:07Z, 5 assets, not a prerelease).
+- PyPI: `pip index versions gflow-cli` → `gflow-cli (0.67.0)`.
+- Release PR: [#667](https://github.com/ffroliva/gflow-cli/pull/667) `chore/release-v0.67.0 → main`, merged with a merge commit, then back-merged into `develop`.
 
 ## NOT verified (recorded, not omitted)
 

gflow_cli-0.68.0/docs/LIVE_VERIFICATION_v0.68.0.md

@@ -0,0 +1,105 @@
+# Live verification — v0.68.0 (pre-release evidence, 2026-09-05)
+
+**Feature:** `gflow update` — self-update through the installer that put gflow-cli here
+(`src/gflow_cli/update_check.py::run_update`, `src/gflow_cli/cli_update.py`) — and the #479
+once-a-day notice rendered as a stderr banner (`src/gflow_cli/cli.py::_print_update_notice`).
+PR [#668](https://github.com/ffroliva/gflow-cli/pull/668). The implementation plan and
+scenario table were folded into project memory at release time
+(`docs/superpowers/memory/windows-running-launcher-blocks-uv-upgrade.md`), per the doc-review
+skill; this file keeps the measurements.
+
+This feature touches no Flow transport, so "live" here means **against the real package
+managers and the real PyPI index, from the installed `gflow.exe` itself** — the surface a
+user actually runs — not against mocks. Nothing in this verification spent credits or
+touched a Flow account.
+
+## Method
+
+A wheel was built from the merged branch with the version lowered to **0.60.1**, installed
+through each manager into a scratch tool directory (`UV_TOOL_DIR` / `PIPX_HOME`, via
+`--find-links` — no `direct_url.json`, so it counts as an index install), the install-time
+pin removed from the receipt / metadata, and `gflow update` run **from that install's own
+`gflow.exe`**, upgrading it to the real PyPI **0.67.0**. Windows 11 Pro, uv 0.8.16,
+pipx 1.8 (`pipx[uv]`).
+
+## Runs
+
+| # | Manager | Command | Exit | Manager exit | Venv after (`gflow --version` through the old launcher) |
+|---|---|---|---|---|---|
+| 1 | `uv tool` | `gflow update --check --json` | **0** | — | unchanged (0.60.1); JSON `update_available: true`, `command: ["uv","tool","upgrade","gflow-cli"]`, `upgraded: false` |
+| 2 | `uv tool` | `gflow update` | **0** | **1** — `Updated gflow-cli v0.60.1 -> v0.67.0` then `failed to copy … gflow.exe … used by another process (os error 32)` | **0.67.0** |
+| 3 | `pipx` | `gflow update` | **0** | 0 — `upgraded package gflow-cli from 0.60.1 to 0.67.0` | **0.67.0** |
+
+Run 2's text output, verbatim shape:
+
+```
+Upgraded gflow-cli 0.60.1 -> 0.67.0 via uv.
+Restart any running `gflow serve` / MCP server to pick it up.
+`uv tool upgrade gflow-cli` exited 1 AFTER installing 0.67.0 — see its output above. On Windows
+this is the running `gflow.exe` launcher, which cannot be replaced while in use; it keeps
+working, and the next update from another shell refreshes it.
+```
+
+## Five-layer ledger
+
+| Layer | Evidence |
+|---|---|
+| 1 · Artifact count | One upgraded venv per manager (2/2); one `--check` report that changed nothing (`uv-receipt.toml` and `Lib/site-packages` untouched, verified by re-running `--version`) |
+| 2 · Magic / identity | `gflow_cli-0.67.0.dist-info` present in both venvs after the run; `gflow_cli-0.60.1.dist-info` gone |
+| 3 · Shape | `--check --json` document carries exactly `{status, installed, latest, update_available, installer, command, upgraded, notes}`; the notes tuple holds the one launcher note on run 2 and nothing on run 3 |
+| 4 · Structlog invariants | `update.installer_detected installer=uv` / `=pipx`, `update.command_finished returncode=1 after=0.67.0` (run 2) and `returncode=0 after=0.67.0` (run 3); the piped-stderr form of the #479 notice printed as **one line** before the command ran (`A newer gflow-cli is available: 0.67.0 (installed 0.60.1). Run \`gflow update\` to upgrade. …`) |
+| 5 · User-confirmable | `gflow --version` → `gflow, version 0.67.0` from the very launcher that was running during the upgrade |
+
+## What the runs changed in the code
+
+1. **A running uv trampoline can be neither overwritten nor renamed.** `os.replace` and
+   `mv` on a running `gflow.exe` both fail (error 32 / "Device or resource busy", measured
+   against `gflow serve`). The first design — rename the launcher aside, restore on failure
+   — moved the idle `flow.exe` and never the one that mattered; it was deleted.
+2. **The manager's exit code is not the outcome.** uv had already installed the wheel when
+   it exited 1. `run_update` re-reads `importlib.metadata.version("gflow-cli")` from a fresh
+   interpreter after the run and reports that (run 2: exit 0 with a note; a zero exit with an
+   unmoved version is exit 11).
+3. `uv tool upgrade` honours an install-time pin silently, and uv's wheel cache is keyed by
+   filename — both bit the test harness before they could bite a user, and both are recorded
+   in the published memory slug.
+
+## Banner
+
+- Piped stderr (subprocess capture): one plain line — layer 4 above, measured on runs 2/3.
+- Terminal: the bordered panel was rendered through the same `Panel` call with a forced
+  terminal console and read back (title `Update available`, version line, `gflow update`
+  line, release-notes URL, silence hint); the `sys.stderr.isatty()` gate is unit-tested on
+  both branches (`tests/test_cli_update.py`). A real interactive-terminal screenshot was
+  **not** taken this cycle.
+
+## Pre-tag gates (filled before signing)
+
+| Gate | Result |
+|---|---|
+| Impeccable Routine on `develop` at 9525cb5 (hygiene, doc links, website PII, website mirror, council memory, ruff, format, pyright) | all green |
+| Offline pytest (`not live and not e2e and not smoke`) on 9525cb5 | 3849 passed, 24 skipped, 1 failed in 6:54 — `tests/features/test_incident_diagnostics_steps.py::test_remote_errors_do_not_expose_local_incident_paths`, a file untouched since July that passes in isolation (1.25 s); a second session was running pytest in the same checkout during the sweep. The release PR's CI run is the authority for the full suite |
+| Branch council on PR #668 (9 dimensions) | D1/D4/D5/D9 YELLOW → all must-fix applied in a7b95ff; D3/D8/D14/D15 GREEN; D2 did not return |
+| PR #668 CI (15 checks incl. SonarCloud) | green on b8b59a3 |
+| Manager runs (this file) | uv: exit 0 + note; pipx: exit 0 |
+| `/gflow:doc-review` mechanical pass (sections 1–7) | PASS — version refs, INDEX cue, evidence file, doc links, website PII + mirror, skill files, CHANGELOG footer, memory index |
+| `/gflow:doc-review` council (3 auditors) | Completeness YELLOW, Cross-reference YELLOW, Drift GREEN. 0 Tier 1. Tier 2 fixed in aedeaaa (llms.txt names `gflow update`; ARCHITECTURE inventory; USER_GUIDE upgrade hop; CI / cache-refresh wording; CONTRIBUTING plan-consolidation note) and in the follow-up doc commit (five-command gate lists in DEVELOPMENT.md and RELEASE.md aligned to the nine; `uv.lock` in RELEASE.md's bump list; NOT-verified lists aligned; CLAUDE.md INDEX size). Tier 3 deferred: `gflow doctor` absent from llms.txt before this pass (now added), verdict-name abbreviations in CONTRIBUTING. Council reports at `tmp/council/0{1,2,3}-*.md` (local-only) |
+
+## Post-tag evidence
+
+To be appended after the tag push: release workflow run URL, `gh release view v0.68.0`,
+PyPI page, and one `pip index versions gflow-cli` read showing 0.68.0.
+
+## NOT verified this cycle (recorded, not omitted)
+
+- **Plain-venv `pip` on Windows** — no venv on this machine runs `gflow.exe` from a pip
+  install; pip removes `Scripts/gflow.exe` and is likely to hit the same lock. The
+  `uv venv`-without-`pip` refusal is unit-tested only.
+- **macOS / Linux for any manager** — POSIX allows replacing a running binary, so the
+  manager should exit 0 there; same code path, same venv-is-truth check. LIKELY, not
+  CONFIRMED.
+- **A real interactive-terminal screenshot of the panel** — rendered through a forced
+  terminal console and read back (see "Banner" above), not photographed on a live tty.
+- **A real newer release on PyPI** for the banner from a normal install — 0.68.0 is the
+  first release after the change, so the first genuine banner a user sees will be for
+  0.68.1 or later. The #479 mechanism itself was live-verified at v0.56.0.

{gflow_cli-0.67.0/website → gflow_cli-0.68.0}/docs/MCP.md

@@ -94,7 +94,7 @@ The server registers three protocol surfaces:
 * `gflow_instructions_toggle_mode(project, enabled, profile)`: Flips the brief-level master switch; cards are left untouched.
 * `gflow_instructions_apply(project, cards, profile)`: Declarative **full-sync** — REPLACES all cards with the given set (destructive; same entry shape as the CLI `instructions apply` file).
 
-CLI↔MCP parity is enforced programmatically: `tests/mcp/test_cli_parity.py` walks every CLI leaf command and fails when one has neither a mapped MCP tool nor an explicit exemption with a stated reason. Note the deliberate asymmetry: `gflow_generate_video` has **no** `instructions` param (unlike `gflow_generate_image`) because the video pipeline (`GenerateVideoRequest` / the worker) has no instructions support — agentic-video is a typed divergence, and a dead parameter would be silently dropped. Both `gflow_generate_image` and `gflow_generate_video` support an `output` parameter mirroring the CLI `-o`/`--output` flag (#414, #415), decoding explicit output destinations in the worker daemon.
+CLI↔MCP parity is enforced programmatically: `tests/mcp/test_cli_parity.py` walks every CLI leaf command and fails when one has neither a mapped MCP tool nor an explicit exemption with a stated reason. Note the deliberate asymmetry: `gflow_generate_video` has **no** `instructions` param (unlike `gflow_generate_image`) because the video pipeline (`GenerateVideoRequest` / the worker) has no instructions support — agentic-video is a typed divergence, and a dead parameter would be silently dropped. Both `gflow_generate_image` and `gflow_generate_video` support an `output` parameter mirroring the CLI `-o`/`--output` flag (#414, #415), decoding explicit output destinations in the worker daemon. `gflow update` is a considered exemption, not a backlog item: the package manager would replace the venv under a live `gflow mcp run` and write its output onto the JSON-RPC stdout channel — the operator runs it and restarts the server. A read-only twin of `gflow update --check` would be harmless; it is the upgrade path if agents ever need version awareness beyond the `initialize` handshake.
 
 ### Prompts (Orchestration templates)
 * `expand_prompt`: Helps the agent structure simple ideas into Google's official 5-component prompt formula (Subject + Action + Location + Composition + Style) before sending them to the generation tools.