gflow-cli 0.15.1__tar.gz → 0.17.0__tar.gz

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/.claude/commands/gflow/check.md

@@ -50,3 +50,10 @@ If the coverage run crashes the current MCP/sandbox session with `Connection clo
 same marker-filtered suite in smaller chunks without coverage and rely on CI for the coverage XML.
 Project pytest defaults already exclude `e2e` and `live`; those markers are explicit,
 credit-spending gates and must be requested with a separate `-m e2e` / `-m live` command.
+
+**Windows agent sessions:** `uv run pytest` is unreliable — invoke
+`.venv/Scripts/python.exe -m pytest` directly, and prefix Python invocations with
+`PYTHONUTF8=1` when output contains non-ASCII. The unscoped full-coverage sweep
+(step 4) can OOM locally (exit 137 / SIGKILL): run the suites scoped to the dirs you
+touched and trust CI for the full coverage gate — **a green full-suite CI run on the
+same tree (e.g. the just-merged PR) satisfies step 4 for release purposes.**

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/.claude/commands/gflow/release.md

@@ -70,6 +70,19 @@ memory) or the release branch will hit conflicts on `pyproject.toml` / `__init__
 
 Run `/gflow:check` — all gates must pass. Abort if any fail.
 
+**4b. Live-verify the release's user-facing features (REQUIRED gate).**
+
+For every new/changed user-facing feature in this release, exercise it against
+live Flow (credit-free wherever possible — image gen, entity attach, upscale, and
+scene/timeline ops cost no Veo credits) and write the evidence to
+`docs/LIVE_VERIFICATION_v<NEW_VERSION>.md` using the 5-layer ledger (file count +
+magic bytes + dimensions/shape + structlog invariants + a user-confirmable
+artifact). Add it to the "what was live-verified" entry in `docs/INDEX.md`. This
+doc shipped for every release v0.7.0→v0.13.0, then lapsed for v0.14.0–v0.15.1 —
+which is why it is now an explicit gate. If a feature genuinely cannot be verified
+this cycle, record that and the reason in the doc; never silently omit it. Stage
+the doc into the release-prep commit (step 11).
+
 **5. Create a release branch off `develop`.**
 
 ```bash
@@ -116,6 +129,12 @@ rg -n "__version__|<OLD_VERSION>|version assertion" tests src pyproject.toml
 
 Run `/gflow:doc-review` — audit all version refs, INDEX completeness, evidence files, skill files, CHANGELOG footer, and memory files. Fix every **FAIL** before continuing. Fold all discovered fixes into the release prep commit.
 
+Also **consolidate shipped planning artifacts** here: extract any durable patterns
+into auto-memory, then remove the now-shipped `docs/superpowers/` plan / spec /
+verification files (keep only in-flight work). `check_repo_hygiene.py` enforces the
+root-doc allowlist, so a stray review doc or session marker left at the repo root
+will fail the gate.
+
 **11. Commit the release prep.**
 
 ```bash

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/.gitignore

@@ -66,6 +66,9 @@ test_assets/debug_*/
 # Phase-2 live-spike capture outputs — NEVER commit (may contain real API payloads)
 scripts/dev/_spike_out/
 
+# Agent session marker — machine/session-local handoff state, regenerated per run
+.continue-here.md
+
 # Live Flow traffic captures — NEVER commit (contain real Bearer tokens / API keys).
 # Diagnostic scripts MUST default-write here, NOT to samples/captured/.
 # Sanitised reference samples (no secrets) can still live under samples/captured/.

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/AGENTS.md

@@ -56,7 +56,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - 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–21, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–22, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 
 ## PR instructions

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] — 2026-06-12
+
+### Added
+
+- Added `verify_flow_profile` in `gflow_cli.auth.verification` using `browser_cookie3` and `httpx` to verify sessions directly from the Chrome cookie store (fast path), with a marker-gated Playwright fallback for encrypted/locked stores. `RealChromeStrategy` now writes the Chrome marker before verification (the fallback reads it) and, on failure, rolls back only a speculative write — a marker that legitimately pre-existed (a previously-verified chrome profile) survives a transient probe failure, and an interrupted verification never leaves an unverified profile claiming the chrome strategy. Cookie extraction is centralised in the new `gflow_cli.auth.cookies` module.
+
+### Fixed
+
+- `gflow_cli.auth.cookies._get_chrome_cookies3` now catches `RuntimeError` (Windows DPAPI failure — `RuntimeError('Failed to decrypt the cipher text with DPAPI')`) in addition to `browser_cookie3.BrowserCookieError`, and re-raises both as `PermissionError` so the Playwright fallback is triggered instead of propagating an unhandled exception.
+- `verify_flow_profile` now retries transient HTTP failures (429/503/504) and network errors up to `_MAX_ATTEMPTS` times with exponential backoff, matching the retry behaviour of the existing Playwright-based `verify_flow_session`.
+
+### Changed
+
+- Entity-attach `WireFormatError` failures (exit 7) now carry a remediation hint pointing at Flow's new full-page media-library UI rollout ([#174](https://github.com/ffroliva/gflow-cli/issues/174)) — affected accounts can stage entities via the include action but the submit never carries `referenceEntities`; the error now explains how to tell which UI an account has and where to follow the fix, instead of the generic file-a-bug hint. Both backstops also emit an `entity_attach_context` discovery field (`video`/`image`) for drift telemetry. New KNOWN_ISSUES entry documents the rollout
+
+## [0.16.0] — 2026-06-12
+
+### Fixed
+
+- **`--reference-entity` no longer fails on non-Portuguese Flow accounts** ([#170](https://github.com/ffroliva/gflow-cli/issues/170)) — the resource-picker include selectors hardcoded the pt-BR caption "Incluir no comando"; they are now locale-free tier cascades (context-menu `add`-ligature anchor + pt/ru/en text fallback), fixing `gflow image t2i --reference-entity`, movie R2V entity attach, and Vozes voice attach for every account language. Failures are now typed (`TransportTimeoutError`, exit 9) with a locale-neutral remediation hint, the matched selector tier is logged (`include_selector_tier`) for drift telemetry, and a new image-side submit backstop raises `WireFormatError` (exit 7) if a staged character never reaches the wire instead of silently returning a text-only generation. Thanks @papushin7987 for the live-verified report
+
+### Added
+
+- **`gflow image upscale <mediaId> --scale 2k|4k`** — upscale a platform-generated image to 2K or 4K (Flow's download-menu 1K/2K/4K options) and save it locally; credit-free. The owning project is resolved from the local catalog (or pass `--project` for images gflow didn't record). 4K requires a Flow Ultra subscription — a non-Ultra 4K request fails fast with exit code 22 (`UpscaleUnavailableError`) rather than a generic 403. Reverse-engineered wire documented in [docs/IMAGE_UPSCALE_RECON.md](docs/IMAGE_UPSCALE_RECON.md); live-verified end-to-end (issue #171)
+
 ## [0.15.1] — 2026-06-10
 
 ### Changed
@@ -1484,7 +1509,9 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.15.1...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...v0.17.0
+[0.16.0]: https://github.com/ffroliva/gflow-cli/compare/v0.15.1...v0.16.0
 [0.15.1]: https://github.com/ffroliva/gflow-cli/compare/v0.15.0...v0.15.1
 [0.15.0]: https://github.com/ffroliva/gflow-cli/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...v0.14.0

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/CLAUDE.md

@@ -22,6 +22,7 @@
 - Slash commands live under `.claude/commands/gflow/` (all prefixed `/gflow:`).
 - Skills under `skills/` are auto-discoverable; `gflow-cli` ships its own at [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md).
 - Auto-memory at `~/.claude/projects/C--development-github-gflow-cli/memory/MEMORY.md` carries cross-session feedback and project state.
+- **Worktrees:** the native `EnterWorktree` tool branches from `origin/main` (the default branch). Feature work integrates via `develop` — after entering a fresh worktree, immediately `git switch -c <type>/<name> origin/develop` and delete the auto-created `worktree-*` branch. On Windows, worktree removal can fail on a file lock (the worktree's `.venv`); `git worktree prune` + manual delete later is fine.
 
 ## MCP GitHub tool — PR body rule (non-negotiable)
 

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/KNOWN_ISSUES.md

@@ -14,6 +14,55 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### Flow's new full-page media-library UI breaks entity attach (A/B rollout)
+
+- **Status:** **Open** — Flow-side staged rollout; tracked in
+  [#174](https://github.com/ffroliva/gflow-cli/issues/174)
+- **Severity:** High · **Affects:** `gflow image t2i --reference-entity` and
+  movie R2V entity attach on accounts that received the new UI, any locale
+
+Flow is A/B-rolling a new full-page media-library UI: clicking **Add Media**
+in the composer **navigates to a library page** (sidebar: All media /
+Characters / Scenes / Tools, with a floating quick-create composer) instead of
+opening the resource-picker dialog. On affected accounts the right-click
+include action still lands (a chip appears), **but the staged entity never
+reaches the submit** — the request carries no `referenceEntities`, so the
+submit backstops raise `WireFormatError` (**exit 7**) instead of silently
+returning a text-only generation as success.
+
+**How to tell which UI your account has:** in the Flow web editor, click
+**Add Media** — a small dialog means the old (working) UI; a navigation to a
+full-page library means the affected new UI.
+
+**Note:** the experiment appears to flap — the affected account observed on
+2026-06-12 00:13 was back on the old dialog UI by 12:48 the same day (variant
+probe, issue #174). If you hit exit 7 on entity attach, re-running later the
+same day may simply work again.
+
+**Workaround:** none yet on affected accounts — the attach gesture for the new
+UI is being reverse-engineered (recon plan in
+[docs/superpowers/plans/2026-06-12-issue-174-library-ui-attach/PLAN.md](docs/superpowers/plans/2026-06-12-issue-174-library-ui-attach/PLAN.md)).
+If you have a second profile/account still on the old UI, entity attach works
+there. Follow [#174](https://github.com/ffroliva/gflow-cli/issues/174) for
+status; please report whether your account shows the dialog or the full-page
+library (plus your locale) on that issue.
+
+### 4K image upscale requires a Flow Ultra subscription
+
+- **Status:** **Open** (by design — a Flow platform limit, not a gflow bug)
+- **Severity:** Low · **Affects:** `gflow image upscale --scale 4k` on non-Ultra accounts
+
+`gflow image upscale <mediaId> --scale 4k` returns **exit code 22**
+(`UpscaleUnavailableError`) on accounts below the Ultra tier — Flow gates 4K
+upscaling behind Ultra (the web UI shows an "Upgrade" button instead of a 4K
+option). The account tier is reported on the wire as `userPaygateTier` but is
+enforced server-side, so gflow cannot grant 4K locally.
+
+**Workaround:** use `--scale 2k` (available on all tiers), or upgrade the Flow
+account to Ultra. If you just upgraded, re-run `gflow auth login --profile <name>`
+to refresh the session before retrying 4K. Wire detail:
+[docs/IMAGE_UPSCALE_RECON.md](docs/IMAGE_UPSCALE_RECON.md) (#171).
+
 ### Image generation returns HTTP 401 — `aisandbox-pa` generation endpoint
 
 - **Status:** **RESOLVED in v0.7.0** — moved to [Resolved](#resolved) section
@@ -332,7 +381,7 @@ issue and not blocked by any code change in this repo.
 
 ### `UiAutomationTransport` selectors locale-agnostic — issue #24 Phase 5 complete
 
-- **Status:** Resolved (pending owner live e2e on non-EN profile) · **Severity:** Low · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24), [issue #94](https://github.com/ffroliva/gflow-cli/issues/94)
+- **Status:** Resolved (pending owner live e2e on non-EN profile) · **Severity:** Low · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24), [issue #94](https://github.com/ffroliva/gflow-cli/issues/94), [issue #170](https://github.com/ffroliva/gflow-cli/issues/170)
 
   `--lang=en-US` removed in PR #127 (2026-05-30). All selector groups now use
   locale-stable anchors: `IMAGE_MODEL_OPTION_SELECTORS` and
@@ -343,6 +392,20 @@ issue and not blocked by any code change in this repo.
   Playwright kwarg (persists across all in-session navigations). Full resolution
   gate: live e2e with `gflow image t2i` (each model) on a non-EN Chrome profile.
 
+  **2026-06-12 correction (issue #170):** the "all selector groups" claim above
+  had two stragglers — `PICKER_INCLUDE_BUTTON` and `PICKER_CONTEXT_INCLUDE`
+  hardcoded the pt-BR caption "Incluir no comando", breaking
+  `--reference-entity` (image t2i), movie R2V entity attach, and Vozes voice
+  attach on every non-Portuguese account (Flow renders in the ACCOUNT language;
+  `?hl=en` cannot override it). Fixed by converting both constants to sequential
+  tier cascades — context-menu Tier 1 is the locale-free `add`-ligature menuitem
+  scoped to the open menu; the Vozes button has no ligature, so pt/ru/en text
+  leads with a lone-iconless-dialog-button structural fallback. The matched tier
+  is emitted as `ui_automation_video.include_selector_tier` (drift telemetry),
+  exhaustion raises typed `TransportTimeoutError` (exit 9) with a locale-neutral
+  remediation hint, and an image-side submit backstop now raises
+  `WireFormatError` when a requested entity never rode the wire.
+
 **Phase 2 progress (2026-05-25, develop / post-v0.8.1, unreleased):**
 
 - **`ONBOARDING_SELECTORS` restructured** — replaced the original 9 English/PT-BR
@@ -565,6 +628,15 @@ success. The expected authenticated response shape is pinned by the
 change surfaces there as a failing test. Start any investigation of a sudden
 `gflow auth login` verification failure at that fixture and `verification.py`.
 
+Since PR #168 the production entry point is `verify_flow_profile`, which reads
+the session cookie **directly from Chrome's SQLite store** via `browser_cookie3`
+(a no-browser fast path) and only falls back to launching Playwright when that
+decryption fails. This adds two more local surfaces to check when verification
+fails unexpectedly: a Windows **DPAPI decrypt failure** (cross-user / cross-machine
+key — surfaces as a `RuntimeError` that `auth/cookies.py` normalizes to
+`PermissionError` to trigger the Playwright fallback) and a **locked cookie DB**
+(Chrome still running holds an exclusive SQLite lock). Both degrade fail-closed.
+
 ---
 
 ## Resolved
@@ -590,8 +662,8 @@ Profiles created before this fix continue to work and display `unknown` in the
 account column. Re-running `gflow auth login` against an existing profile backfills
 the `.gflow_account` file.
 
-See [AUTHENTICATION.md § Profile naming](AUTHENTICATION.md#profile-naming) for the
-new naming convention and [AUTHENTICATION.md § gflow auth list](AUTHENTICATION.md#gflow-auth-list)
+See [AUTHENTICATION.md § Profile naming](docs/AUTHENTICATION.md#profile-naming) for the
+new naming convention and [AUTHENTICATION.md § gflow auth list](docs/AUTHENTICATION.md#gflow-auth-list)
 for the updated `--json` schema.
 
 ---

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.15.1
+Version: 0.17.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
@@ -37,6 +37,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Video
 Requires-Python: >=3.11
+Requires-Dist: browser-cookie3>=0.20.1
 Requires-Dist: click>=8.1.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: platformdirs>=4.0.0

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/RELEASE.md

@@ -68,28 +68,43 @@ python -m pip install --pre gflow-cli
    uv run pyright src
    uv run python -m pytest -q --cov=gflow_cli
    ```
-4. Update the version in:
+4. **Live-verify the release's user-facing features and record the evidence.**
+   **Required gate — do not skip.** Exercise each new/changed user-facing feature
+   against live Flow (credit-free wherever possible — image gen, entity attach,
+   upscale, and scene/timeline ops cost no Veo credits) and write the result to
+   `docs/LIVE_VERIFICATION_vX.Y.Z.md` using the 5-layer ledger (file count + magic
+   bytes + dimensions/shape + structlog invariants + user-confirmable artifact).
+   Then add it to the "what was live-verified" entry in `docs/INDEX.md`. Every
+   release v0.7.0→v0.13.0 had this doc; it lapsed for v0.14.0–v0.15.1 — that gap is
+   the reason this is now an explicit step. If a feature genuinely cannot be live-
+   verified this cycle, say so in the doc with the reason; never silently omit it.
+5. **Consolidate shipped planning artifacts.** Extract any durable patterns into
+   auto-memory, then remove the now-shipped `docs/superpowers/` plan / spec /
+   verification files (keep only in-flight work). Stale review docs and session
+   markers do not belong in the repo root. (Enforced by `check_repo_hygiene.py` —
+   see the root-doc allowlist.)
+6. Update the version in:
    - `pyproject.toml`
    - `src/gflow_cli/__init__.py`
    - any tests that assert the package version
-5. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
+7. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
    release section.
-6. Commit the release prep:
+8. Commit the release prep:
    ```bash
-   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests
+   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests docs
    git commit -m "chore(release): vX.Y.Z"
    ```
-7. 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.
+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.
    ```bash
    git tag -s vX.Y.Z -m "vX.Y.Z"
    git push origin main
    git push origin vX.Y.Z
    ```
-8. Watch the release workflow:
-   <https://github.com/ffroliva/gflow-cli/actions/workflows/release.yml>
-9. Confirm the new version appears on:
-   - <https://pypi.org/project/gflow-cli/>
-   - <https://github.com/ffroliva/gflow-cli/releases>
+10. Watch the release workflow:
+    <https://github.com/ffroliva/gflow-cli/actions/workflows/release.yml>
+11. Confirm the new version appears on:
+    - <https://pypi.org/project/gflow-cli/>
+    - <https://github.com/ffroliva/gflow-cli/releases>
 
 ## Known Historical Quirk
 

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/docs/AUTHENTICATION.md

@@ -364,6 +364,27 @@ Run: gflow auth login --profile default
 
 Re-running `auth login` refreshes the cookies in place — no other state is lost.
 
+## Session verification (cookie-store fast path)
+
+Since v0.17.0, profile verification (run by `gflow auth login --browser chrome` after
+capture) is handled by `gflow_cli.auth.verification.verify_flow_profile`, which probes
+Flow's `/fx/api/auth/session` endpoint **directly from the Chrome cookie store** via
+`browser_cookie3` + `httpx` — no browser launch needed (contributed in PR #168 by
+@3mora2). Two hardening behaviors:
+
+- **Encrypted/locked store fallback** — if the cookie store can't be read (e.g.
+  Windows DPAPI decryption fails, or the store is locked by a running Chrome), the
+  verifier falls back to a marker-gated Playwright probe. The chrome marker is written
+  before verification so the fallback can find the profile; on failure only a
+  *speculative* marker write is rolled back — a previously-verified profile survives a
+  transient probe failure.
+- **Transient-error retry** — HTTP 429/503/504 and network errors retry with
+  exponential backoff before the verifier gives up.
+
+The outcome is the same `AUTHENTICATED` / no-session decision documented under
+[`gflow auth status`](#gflow-auth-status); only the transport is faster. Cookie
+extraction lives in `gflow_cli.auth.cookies`.
+
 ## Threat model & limits
 
 | Threat | Mitigation |

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/docs/CHARACTER.md

@@ -375,7 +375,8 @@ convenience later.
     generate) so Flow's JS sets `entityContext` and passes the WAF; gflow captures `media[]`/`workflows[]`
     from the response. Reuse gflow's prompt-submit + response-capture machinery (`ui_automation.py`), but in
     the character-editor context (NOT the new-project flow). Video `--character` reuse = resource picker
-    (`Pesquisar recursos` → Personagens → *Incluir no comando*) → generate; mirrors #123 `_attach_likeness`.
+    (search resources → Personagens → *include-in-prompt* context-menu action; captions are localized,
+    selectors locale-free since issue #170) → generate; mirrors #123 `_attach_likeness`.
     All selectors **ligature/structural only** (language-agnostic).
   - **Cost reality:** the feature is UI-automation-heavy (new character-editor + picker selectors), not the
     "mostly REST" earlier framing. Structural metadata is REST; the value-generating steps are UI.

gflow_cli-0.17.0/docs/IMAGE_UPSCALE_RECON.md

@@ -0,0 +1,115 @@
+# Image Upscale — Reverse-Engineering Recon
+
+> Status: **recon complete, pre-implementation**. Wire empirically captured 2026-06-11
+> (denon82 Pro account, project `ffb768fb…`). Spikes: `scripts/dev/spike_image_upscale_drive.py`
+> (UI drive + capture) and `scripts/dev/spike_image_upscale_rest_probe.py` (schema + REST probe).
+
+## Feature
+
+Flow's image editor download menu offers **1K Original / 2K Upscaled / 4K Upscaled**. gflow
+today saves only the 1K original (the pre-signed `fifeUrl` from the generation response). This
+feature adds `gflow image upscale <mediaId> --scale 2k|4k` to fetch the upscaled variant.
+
+Scope: **platform-generated images only** (referenced by `mediaId`). Uploaded images are not
+supported by this endpoint. **4K is Ultra-tier-gated**; Pro accounts see "Upgrade" in the UI.
+
+## Wire protocol
+
+### Endpoint
+```
+POST https://aisandbox-pa.googleapis.com/v1/flow/upsampleImage
+```
+Same host + auth class as image generation (`batchGenerateImages`).
+
+### Request body
+```json
+{
+  "mediaId": "<source-image-uuid>",
+  "targetResolution": "UPSAMPLE_IMAGE_RESOLUTION_2K",
+  "clientContext": {
+    "recaptchaContext": {
+      "token": "<reCAPTCHA-Enterprise-token>",
+      "applicationType": "RECAPTCHA_APPLICATION_TYPE_WEB"
+    },
+    "projectId": "<project-that-owns-the-media>",
+    "sessionId": ";<epoch_ms>",
+    "tool": "PINHOLE",
+    "userPaygateTier": "PAYGATE_TIER_ONE"
+  }
+}
+```
+- `targetResolution` enum: `UPSAMPLE_IMAGE_RESOLUTION_2K` | `UPSAMPLE_IMAGE_RESOLUTION_4K`.
+  1K = original (no API call — gflow already has it).
+- **The FULL `clientContext` is required.** A minimal `{recaptchaContext}` body returns
+  **403 even with a valid token** (confirmed by live smoke). All five fields are needed;
+  `projectId` (the project owning the media) is load-bearing.
+- `sessionId` format is `;<epoch_ms>` (e.g. `;1781190457842`), same as image generation.
+- `userPaygateTier` is **where the account tier surfaces on the wire** (`PAYGATE_TIER_ONE`
+  on a Pro account). It is client-reported telemetry — the server enforces the real tier
+  independently (a non-Ultra 4K request 403s regardless), so it is not a security control.
+
+### reCAPTCHA action — `IMAGE_GENERATION`
+The token MUST be minted with action **`IMAGE_GENERATION`** (uppercase). reCAPTCHA Enterprise
+scores by action; the guessed `"upsampleImage"` scored low and 403'd. Captured live by hooking
+`grecaptcha.enterprise.execute` (`scripts/dev/spike_image_upscale_recaptcha_action.py`). The
+site key is page-discovered, so it auto-matches; minting on the bootstrap page is fine — the
+action was the only gap. **Live-verified 2026-06-11**: a 2K upscale wrote a 3.8 MB JPEG.
+
+### Response
+```json
+{ "encodedImage": "<base64>" }
+```
+- Single field. ~3.8–5.1 MB base64 observed (varies by source image). Decode → write image bytes.
+- Synchronous: one call returns the result. **No async poll/status loop** (unlike video gen).
+
+## Transport decision — browser required, REST is dead
+
+| Approach | Viable? | Evidence |
+|---|---|---|
+| Pure REST / Bearer-only | ❌ No | Bearer `ya29` + **no** reCAPTCHA token → **403** (probed with and without `clientContext`) |
+| Browser reCAPTCHA-mint + POST | ✅ Yes | UI drive returns 200; reuses the existing `batchGenerateImages` transport |
+| Hybrid (browser submit + Bearer poll) | ⚠️ N/A | No poll/download phase exists — response is synchronous inline base64 |
+
+**Conclusion:** reCAPTCHA token is **mandatory**. Reuse the existing image-generation reCAPTCHA
+minting path; there is no Bearer-only slice to peel off. See [REST-path capability matrix] — a
+generative-class op stays reCAPTCHA-gated.
+
+## Tier gating (4K = Ultra)
+
+- 4K is Ultra-only. On Pro, the UI renders "Fazer upgrade" (Upgrade) instead of a clickable 4K.
+- Account tier is **NOT** in `GET /fx/api/auth/session` (only `user` / `expires` / `access_token`).
+  It surfaces via the upsell recommendations (`fetchUserRecommendations` onramp list) and is
+  enforced server-side. A 4K request on a non-Ultra account is expected to 403 (permission), which
+  must be distinguished from a WAF/reCAPTCHA 403.
+- Session staleness is real: an idle session returns `error: ACCESS_TOKEN_REFRESH_NEEDED` and
+  re-auths before the call succeeds — so a freshly-upgraded account may need a session refresh
+  before 4K unlocks.
+
+## UI navigation facts (for the spike/transport)
+
+- **Cold-loading `/project/<pid>/edit/<mediaId>` 500s** ("Algo deu errado"). Must land on the
+  gallery `/project/<pid>` then click the `a[href*=<mediaId>]` tile (in-app SPA routing).
+- A "What's new" changelog modal overlays the gallery but does **not** block the href tile click.
+- Working selectors (locale leaks into the UI — match language-neutral tokens):
+  - Download button: `button:has(i.google-symbols:text-is('download'))`
+  - Scale menu item: `[role='menuitem']:has-text('2K')` (and `'4K'`)
+  - pt labels are 1K="Tamanho original", 2K/4K="Aumentada" — **never** match on "Aumentada".
+
+## Implementation sketch (from `/gflow:predict` GO, 7.5/10)
+
+- `api/routes.py`: `UPSAMPLE_IMAGE = f"{FLOW_API_BASE}/flow/upsampleImage"`.
+- `api/image.py`: frozen `UpsampleImageRequest(media_id, target_resolution, recaptcha_token="")`;
+  `TargetResolution` enum with `from_cli("2k"|"4k")`.
+- `api/client.py`: `upsample_image()` — mint reCAPTCHA (existing path), POST, validate + decode
+  `encodedImage` with `MAX_UPSAMPLE_B64_LEN ≈ 50 MB` cap + `del` + PNG/JPEG magic-byte check
+  (mirror `concatenate_scene`).
+- `cli_image.py`: `gflow image upscale <mediaId> --scale 2k|4k [--out]`.
+- `errors.py`: `UpscaleUnavailableError` (exit 22), distinct from WAF/reCAPTCHA 403; **no auto-retry**
+  on a 4K 403.
+- Never log `encodedImage`. Record the output via `OperationRecorder` honoring the redaction gate.
+- Discover mediaIds via the existing `gflow data list images`.
+
+## Credit cost
+
+Image operation → expected **credit-free** (only video generation spends credits). Not yet
+stress-confirmed; treat as free but do not batch aggressively (per-profile WAF heat).

{gflow_cli-0.15.1 → gflow_cli-0.17.0}/docs/INDEX.md

@@ -34,6 +34,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/DATA_LAYER.md](DATA_LAYER.md)** | Local SQLite catalog: goals, schema, recording flow, redaction, `gflow data` CLI, migrations, extension guide | Anything touching `gflow_cli.data`, debugging missing rows, building I2V/repair tooling, auditing what is stored |
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
 | **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
+| **[docs/IMAGE_UPSCALE_RECON.md](IMAGE_UPSCALE_RECON.md)** | `gflow image upscale` wire protocol: `upsampleImage` endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action `IMAGE_GENERATION`, inline base64 response, 4K Ultra-gating, REST-is-dead proof | Working on `gflow image upscale`, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Gemini CLI, Aider, etc. | Any agent wanting to use gflow-cli correctly |
 | **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |
@@ -84,6 +85,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"How do I run with multiple Google accounts?"** → [AUTHENTICATION § Multiple accounts](AUTHENTICATION.md#multiple-accounts)
 **"How do I know which Google account a profile is signed into?"** → [AUTHENTICATION § gflow auth list](AUTHENTICATION.md#gflow-auth-list)
 **"Why is my profile named 'default' and how do I rename it?"** → [AUTHENTICATION § Profile naming](AUTHENTICATION.md#profile-naming)
+**"How does login verification work without launching a browser?"** → [AUTHENTICATION § Session verification](AUTHENTICATION.md#session-verification-cookie-store-fast-path) (cookie-store fast path, v0.17.0)
 **"How does the layered structure work?"** → [ARCHITECTURE § Layers](ARCHITECTURE.md#layers)
 **"What env var should I set for X?"** → [CONFIGURATION § Reference](CONFIGURATION.md#reference)
 **"What does gflow remember after a generation finishes?"** → [DATA_LAYER § What is recorded](DATA_LAYER.md#what-is-recorded)
@@ -109,7 +111,8 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → v0.15.0 / v0.14.x: no dedicated live-verification doc (CI + the v0.13.0 baseline). Latest doc: [LIVE_VERIFICATION_v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · prior: [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.17.0](LIVE_VERIFICATION_v0.17.0.md) (#168 cookie verification live e2e_auth; #177 exit-7 hint recorded not-triggerable, credit-free). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)
 **"What is the jitter matrix evidence for `gflow image batch`?"** → [`LIVE_VERIFICATION_image_batch.md`](LIVE_VERIFICATION_image_batch.md) — jitter matrix evidence for `gflow image batch` (always-same-project mode)

gflow_cli-0.17.0/docs/LIVE_VERIFICATION_v0.16.0.md

@@ -0,0 +1,77 @@
+# Live verification — v0.16.0
+
+> Evidence record for the v0.16.0 release. v0.16.0 ships two features: locale-free
+> resource-picker include selectors (issue #170, PR #173) and `gflow image upscale`
+> (issue #171, PR #172). Backfilled 2026-06-12 to close the live-verification
+> documentation gap that opened after v0.13.0 (see docs/INDEX.md).
+
+## Summary
+
+- **Verified by:** ffroliva (Claude Code)
+- **Dates:** #171 upscale — 2026-06-11 (feature branch); #170 selectors — 2026-06-12 (released PyPI artifact)
+- **gflow-cli version:** 0.16.0
+- **Status:** 🟢 Green — both features live-verified credit-free; no Veo credits spent
+
+All verification below is **credit-free**: image generation, character-entity attach,
+and image upscale are non-Veo operations (see the credits-are-videos-only note in
+`KNOWN_ISSUES.md`). No video generation was exercised for this release.
+
+## 1. Quality gates
+
+- [x] **Lint/format** — `ruff check` + `ruff format --check` clean (`src` + `tests`).
+- [x] **Type check** — `pyright src`: 0 errors.
+- [x] **Unit + BDD tests** — full suite green in CI across Python 3.11 / 3.12 / 3.13 (PR #173, PR #172).
+- [x] **Repo hygiene + doc links** — `check_repo_hygiene.py` + `check_doc_links.py` green.
+
+## 2. Issue #170 — locale-free picker include selectors (PR #173)
+
+The pt-BR-hardcoded resource-picker include selectors broke entity attach on every
+non-Portuguese account. PR #173 replaced them with sequentially-probed tier cascades
+(locale-invariant ligature anchor first, then localized-text fallback) and added an
+image-side submit backstop that fails loudly (`WireFormatError`, exit 7) if a staged
+entity never reaches the wire.
+
+### E2E evidence (live Flow, credit-free)
+
+| Layer | Criterion | Outcome |
+|---|---|---|
+| Selector tier | `include_selector_tier=icon` logged (locale-free anchor matched) | **PASS** |
+| Attach event | `ui_automation.character_entity_attached` fired | **PASS** |
+| Submit backstop | `ui_automation.image_entities_attached` — entity rode the wire | **PASS** |
+| Output artifact | t2i produced a JPEG, **768×1376**, character identity visibly preserved | **PASS** |
+| Version | all events emitted at `cli_version 0.16.0` | **PASS** |
+
+- **Pre-merge:** live credit-free `gflow image t2i --reference-entity` on **promo-denon82**
+  (pt-BR profile). Recon harness: `scripts/dev/spike_issue170_picker_locale_recon.py`.
+- **Released-artifact re-verification (2026-06-12):** installed `gflow-cli==0.16.0` from
+  PyPI (global `uv tool`) and re-ran the same flow on promo-denon82 — all four layers
+  above green at `cli_version 0.16.0`. **5-layer ledger PASS.**
+- The backstop earned its keep immediately: it converted Flow's new full-page library-UI
+  A/B (issue #174) from a silent text-only "success" into a typed exit-7 failure on its
+  first live encounter.
+
+## 3. Issue #171 — `gflow image upscale` (PR #172)
+
+`gflow image upscale <mediaId> --scale 2k|4k` upscales a platform-generated image via
+Flow's `POST /v1/flow/upsampleImage` (reCAPTCHA-gated, inline base64 response). 4K is
+Ultra-gated and fails fast with `UpscaleUnavailableError` (exit 22) on lower tiers.
+
+### E2E evidence (live Flow, credit-free)
+
+| Layer | Criterion | Outcome |
+|---|---|---|
+| Wire | `POST /v1/flow/upsampleImage` accepted (full 5-field `clientContext`, action `IMAGE_GENERATION`) | **PASS** |
+| File written | local JPEG written, **3,799,245 bytes** | **PASS** |
+| Magic bytes | header `FF D8 FF` (valid JPEG) | **PASS** |
+| Byte fidelity | written bytes matched the decoded wire payload | **PASS** |
+| Tier gate | 4K returns exit 22 (`UpscaleUnavailableError`) on non-Ultra, not a generic 403 | **PASS** |
+
+- Verified 2026-06-11 on the `feature/image-upscale` branch (= the code released as
+  v0.16.0): `gflow image upscale <mediaId> --scale 2k --project <pid>` end-to-end.
+- Wire protocol documented in [`docs/IMAGE_UPSCALE_RECON.md`](IMAGE_UPSCALE_RECON.md).
+
+## 4. Documentation
+
+- `CHANGELOG.md` — v0.16.0 entry covers both features.
+- `KNOWN_ISSUES.md` — 4K-Ultra limit documented; library-UI A/B (#174) tracked.
+- `docs/IMAGE_UPSCALE_RECON.md` — reverse-engineered upscale wire.