gflow-cli 0.15.0__tar.gz → 0.16.0__tar.gz

{gflow_cli-0.15.0 → gflow_cli-0.16.0}/AGENTS.md

@@ -76,10 +76,12 @@ The `skills/` directory ships installable agent skill docs in plain Markdown wit
 | `gflow-cli` | [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md) | User wants to run any `gflow` command — auth, T2V, I2V, T2I, I2I, batch |
 | `predict` | [`skills/predict/SKILL.md`](skills/predict/SKILL.md) | Pre-implementation adversarial analysis before any high-stakes change |
 | `scenario` | [`skills/scenario/SKILL.md`](skills/scenario/SKILL.md) | Edge-case explorer after a predict GO/CAUTION |
+| `plan` | [`skills/plan/SKILL.md`](skills/plan/SKILL.md) | Create a structured task-by-task implementation plan for a feature |
+| `status` | [`skills/status/SKILL.md`](skills/status/SKILL.md) | Show current plan state, progress, and next unchecked task |
 | `pr-council-review` | [`skills/pr-council-review/SKILL.md`](skills/pr-council-review/SKILL.md) | Multi-dimensional PR council review |
 
 **Cursor / Aider / Codex / Gemini CLI:** paste or include the relevant `SKILL.md` in your system context.
-**Claude Code:** symlink `skills/gflow-cli` to `~/.claude/skills/gflow-cli` to register the skill; the `/gflow:` slash commands (in `.claude/commands/gflow/`) are auto-discovered from the project directory.
+**Claude Code:** the `/gflow:` slash commands in `.claude/commands/gflow/` are auto-discovered when the project is open — no extra setup needed. To register a skill globally, copy the command file to `~/.claude/commands/`.
 **Custom agents:** fetch `skills/gflow-cli/SKILL.md` into your knowledge base before answering gflow questions.
 
 The SkillOpt harness at `scripts/dev/skillopt/` measures how accurately each skill guides an agent, and supports multiple providers (Anthropic, OpenAI-compat, Gemini, local models). See [`scripts/dev/skillopt/README.md`](scripts/dev/skillopt/README.md).

{gflow_cli-0.15.0 → gflow_cli-0.16.0}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Added `--disable-dev-shm-usage` to Chrome launch args in both `FlowApiClient._persistent_context_kwargs()` and `UiAutomationTransport.setup()` — prevents OOM in Docker containers with the default 64 MB `/dev/shm` allocation; no effect on developer machines with adequate shared memory
+- README Stats badges hardened against shields.io outages — GitHub-stat badges now pass `cacheSeconds=3600` (mitigates shields.io's shared GitHub token-pool exhaustion, the "Unable to select next GitHub token from pool" error) and the PyPI downloads badge moved from `img.shields.io/pypi/dm` to pepy.tech (pypistats rate-limits shields.io upstream)
+
+### Added
+
+- `scripts/diag/` directory — documented home for investigation scripts that require a live authenticated profile; includes `memory_profile.py` (Chrome process-tree RSS profiler for issue #155), `capture_flow_traffic.py`, and `recaptcha_mint.py` (both moved from `scripts/` root via git mv, history preserved)
+
+### Fixed
+
+- Video status poll now raises `AuthExpiredError` (exit 3) immediately on HTTP 401 from `batchCheckAsyncVideoGenerationStatus` instead of silently timing out after 600 s with a bare `TimeoutError` (exit 1) — session expiry is now detected mid-workflow, not only at login time (issue #156)
+
 ## [0.15.0] — 2026-06-09
 
 ### Added
@@ -1469,7 +1494,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.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...HEAD
+[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
 [0.13.0]: https://github.com/ffroliva/gflow-cli/compare/v0.12.0...v0.13.0

{gflow_cli-0.15.0 → gflow_cli-0.16.0}/KNOWN_ISSUES.md

@@ -14,6 +14,22 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### 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 +348,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 +359,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

{gflow_cli-0.15.0 → gflow_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.15.0
+Version: 0.16.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
@@ -196,13 +196,13 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Stats
 
-[![GitHub stars](https://img.shields.io/github/stars/ffroliva/gflow-cli?style=social)](https://github.com/ffroliva/gflow-cli/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/ffroliva/gflow-cli?style=social)](https://github.com/ffroliva/gflow-cli/network/members)
-[![GitHub watchers](https://img.shields.io/github/watchers/ffroliva/gflow-cli?style=social)](https://github.com/ffroliva/gflow-cli/watchers)
-[![GitHub issues](https://img.shields.io/github/issues/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/issues)
-[![GitHub pull requests](https://img.shields.io/github/issues-pr/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/pulls)
-[![GitHub last commit](https://img.shields.io/github/last-commit/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/commits/main)
-[![GitHub repo size](https://img.shields.io/github/repo-size/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli)
-[![PyPI downloads](https://img.shields.io/pypi/dm/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
+[![GitHub stars](https://img.shields.io/github/stars/ffroliva/gflow-cli?style=social&cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/ffroliva/gflow-cli?style=social&cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/network/members)
+[![GitHub watchers](https://img.shields.io/github/watchers/ffroliva/gflow-cli?style=social&cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/watchers)
+[![GitHub issues](https://img.shields.io/github/issues/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/issues)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/pulls)
+[![GitHub last commit](https://img.shields.io/github/last-commit/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/commits/main)
+[![GitHub repo size](https://img.shields.io/github/repo-size/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli)
+[![PyPI downloads](https://static.pepy.tech/badge/gflow-cli/month)](https://pepy.tech/project/gflow-cli)
 
 If `gflow-cli` saves you time, please ⭐ the repo — it is the cheapest way to support the project.

{gflow_cli-0.15.0 → gflow_cli-0.16.0}/README.md

@@ -132,13 +132,13 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Stats
 
-[![GitHub stars](https://img.shields.io/github/stars/ffroliva/gflow-cli?style=social)](https://github.com/ffroliva/gflow-cli/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/ffroliva/gflow-cli?style=social)](https://github.com/ffroliva/gflow-cli/network/members)
-[![GitHub watchers](https://img.shields.io/github/watchers/ffroliva/gflow-cli?style=social)](https://github.com/ffroliva/gflow-cli/watchers)
-[![GitHub issues](https://img.shields.io/github/issues/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/issues)
-[![GitHub pull requests](https://img.shields.io/github/issues-pr/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/pulls)
-[![GitHub last commit](https://img.shields.io/github/last-commit/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/commits/main)
-[![GitHub repo size](https://img.shields.io/github/repo-size/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli)
-[![PyPI downloads](https://img.shields.io/pypi/dm/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
+[![GitHub stars](https://img.shields.io/github/stars/ffroliva/gflow-cli?style=social&cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/ffroliva/gflow-cli?style=social&cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/network/members)
+[![GitHub watchers](https://img.shields.io/github/watchers/ffroliva/gflow-cli?style=social&cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/watchers)
+[![GitHub issues](https://img.shields.io/github/issues/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/issues)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/pulls)
+[![GitHub last commit](https://img.shields.io/github/last-commit/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli/commits/main)
+[![GitHub repo size](https://img.shields.io/github/repo-size/ffroliva/gflow-cli?cacheSeconds=3600)](https://github.com/ffroliva/gflow-cli)
+[![PyPI downloads](https://static.pepy.tech/badge/gflow-cli/month)](https://pepy.tech/project/gflow-cli)
 
 If `gflow-cli` saves you time, please ⭐ the repo — it is the cheapest way to support the project.

{gflow_cli-0.15.0 → gflow_cli-0.16.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.16.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.0 → gflow_cli-0.16.0}/docs/INDEX.md

@@ -34,9 +34,11 @@ 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 |
+| **[scripts/diag/README.md](../scripts/diag/README.md)** | Diagnostic investigation scripts — run against a live authenticated profile to capture wire samples, measure Chrome memory, or mint reCAPTCHA tokens | Running a one-off investigation against a live Flow session; establishing baseline measurements for issue #155 |
 
 ## Agent commands
 
@@ -54,6 +56,9 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 | `/gflow:release` | Full release flow (calls `/gflow:changelog` + `/gflow:check`) | Cutting a new version |
 | `/gflow:predict <proposal>` | 5-persona pre-implementation analysis → GO / CAUTION / STOP | Before any high-stakes design decision (new transport, auth change, selector redesign, schema migration) |
 | `/gflow:scenario <feature>` | 12-dimension edge-case explorer → severity-ranked scenario table + BDD skeleton | After predict GO/CAUTION; before `/gflow:plan` |
+| `/gflow:pr-council-review [PR#]` | Multi-dimensional council review of an open PR (5 baseline + adaptive dimensions) | Before merging any non-trivial PR; mandatory for auth/transport/data changes |
+| `/gflow:branch-review` | Same council review run against the current local feature branch (no PR needed) | Pre-PR self-audit; after predict/scenario on a high-stakes branch |
+| `/gflow:doc-review` | Systematic council-driven audit of documentation completeness and drift | Before cutting a release; after major documentation changes |
 
 **Governance:** commands are executable docs — they decay like any doc. When a phase advances or a file path changes, update the relevant command in the same commit. `/gflow:release` includes a staleness review step.
 
@@ -90,6 +95,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"How do I use this project's skills in Cursor / Codex / Gemini CLI / Aider?"** → [skills/README.md](../skills/README.md#use-with-other-agents)
 **"How do I benchmark a skill doc against real tasks?"** → [scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)
 **"How do I compare Claude vs GPT-4o vs Gemini on gflow tasks?"** → `python scripts/dev/skillopt/harness.py --provider openai --model gpt-4o` (see [skillopt README](../scripts/dev/skillopt/README.md))
+**"What does Chrome actually use in RAM during a generation?"** → run `uv run python scripts/diag/memory_profile.py --profile NAME` (see [scripts/diag/README.md](../scripts/diag/README.md))
 **"How do I report a security issue?"** → [SECURITY § Reporting](SECURITY.md#reporting)
 **"What branch do I work on? How do I name it?"** → [DEVELOPMENT § Branching model](DEVELOPMENT.md#branching-model)
 **"How do I handle an external GitHub PR?"** → [GITHUB § Scenario Matrix](GITHUB.md#scenario-matrix)
@@ -104,7 +110,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → [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?"** → 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 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.15.0 → gflow_cli-0.16.0}/docs/MOVIE.md

@@ -100,10 +100,13 @@ attached by driving Flow's resource picker:
 1. Click **Add Media** in the composer (references sub-mode).
 2. Switch to the **Personagens** (Characters) tab.
 3. **Right-click** the entity tile — addressed by entity id as
-   `data-tile-id="fe_id_<entityId>"` — and choose **"Incluir no comando"** from
-   the context menu. *(A plain left-click navigates into the character editor;
-   the inline "Incluir" button on the **Tudo** tab attaches the character's
-   thumbnail as a plain image, not the entity.)*
+   `data-tile-id="fe_id_<entityId>"` — and choose the **include-in-prompt**
+   action from the context menu (the `add`-ligature menu item; its caption is
+   localized per account language, e.g. "Incluir no comando" on pt-BR or
+   "Добавить в запрос" on ru — selectors are locale-free since issue #170).
+   *(A plain left-click navigates into the character editor; the inline include
+   button on the **Tudo** tab attaches the character's thumbnail as a plain
+   image, not the entity.)*
 
 This puts `referenceEntities:[{entityId}]` on the
 `video:batchAsyncGenerateVideoReferenceImages` **request**. Flow's **response**

{gflow_cli-0.15.0 → gflow_cli-0.16.0}/docs/USAGE.md

@@ -105,6 +105,44 @@ UUID=$(gflow image upload hero.png | awk '/Asset UUID:/ {print $3}')
 gflow image i2i "make it cinematic" --ref "$UUID"
 ```
 
+## `gflow image upscale`
+
+Upscale a **platform-generated** image to 2K or 4K (the same 1K/2K/4K options Flow's
+download menu offers) and save it locally. Uploaded images are not supported.
+
+```text
+gflow image upscale MEDIA_ID --scale 2k|4k [OPTIONS]
+
+Arguments:
+  MEDIA_ID                  UUID of a Flow-generated image (find one with
+                            `gflow data list images`).
+
+Options:
+  --scale [2k|4k]           Target resolution. 4k requires a Flow Ultra
+                            subscription; 1k is the original (no upscale).
+  --project ID              Project that owns the image. Resolved from the local
+                            catalog when omitted; pass it explicitly for images
+                            gflow didn't record (e.g. generated in the web UI).
+  --out PATH                Output directory (see "Output paths" below).
+  --profile NAME            Profile name (overrides default).
+```
+
+```bash
+# Upscale a previously generated image to 2K (project auto-resolved from the catalog)
+gflow image upscale 3a56bb5e-92a2-44f4-9992-3c6a9bf0cd14 --scale 2k
+
+# Upscale an image generated in the Flow web UI (not in the local catalog)
+gflow image upscale <mediaId> --scale 2k --project <projectId>
+```
+
+Notes:
+
+- **Credit-free** — upscaling is an image operation and spends no credits.
+- **4K is Ultra-only.** On a non-Ultra account a 4K request fails with exit code 22
+  (`UpscaleUnavailableError`) and a hint to use `--scale 2k` or upgrade.
+- The result is saved as `<output_dir>/images/<YYYY-MM-DD>/<mediaId>_<scale>.<ext>`
+  (extension matches the returned format — usually `.jpg`).
+
 ## `gflow image t2i`
 
 Generate 1–4 images from one text prompt, or run a shell-friendly batch of 1–50

gflow_cli-0.16.0/docs/superpowers/plans/2026-06-11-image-upscale/PLAN.md

@@ -0,0 +1,206 @@
+# Image Upscale Implementation Plan
+
+> **For agentic workers:** Run `/gflow:status --feature image-upscale` to find the next
+> unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Add `gflow image upscale <mediaId> --scale 2k|4k` so a user can fetch Flow's
+server-side 2K/4K upscaled variant of a platform-generated image and save it locally.
+
+**Architecture:** Reuses the existing image-generation reCAPTCHA browser transport — same host
+(`aisandbox-pa.googleapis.com`) and `recaptchaContext` shape as `batchGenerateImages`. New work is
+glue: a route constant, a frozen request value object, a synchronous `FlowApiClient.upsample_image()`
+that mints a reCAPTCHA token, POSTs, and decodes the inline `{encodedImage: base64}` (mirroring
+`concatenate_scene`'s cap + `del` + magic-byte pattern), a new exit-coded error, and a Click
+subcommand. No transport-Protocol change (it's a client-level op like `concatenate_scene`). No new
+auth, no new persistent state, no async poll loop.
+
+**Tracking issue:** [#171](https://github.com/ffroliva/gflow-cli/issues/171)
+
+**Predict verdict:** GO — confidence 7.5/10. Recon: `docs/IMAGE_UPSCALE_RECON.md`. Scenario matrix
+complete (20 scenarios; 12 Critical/High are must-cover).
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| Critical | 403 ambiguity: tier-gate (4K/Pro) vs WAF heat vs expired token all return 403 | Disambiguate by response context; `UpscaleUnavailableError` (exit 22) for tier; **never auto-retry** a 4K 403 |
+| Critical | ~5 MB `encodedImage` base64 leaks into logs / error context | Never log the field; decode then `del`; structlog carries size only |
+| High | Pathological oversized base64 (4K PNG) → OOM | `MAX_UPSAMPLE_B64_LEN` (~50 MB) cap **before** decode; typed error |
+| High | Response missing `encodedImage` / decodes to non-image | `WireFormatError` (redacted discovery payload); PNG/JPEG magic-byte check |
+| High | Per-profile reCAPTCHA/WAF heat (a 4th gated op) | One upscale per invocation; no implicit batch; document the heat |
+| High | mediaId injection / malformed input | UUID allowlist; reject before any request fires |
+| Medium | Selector drift (download button / scale menu) on Flow UI update | Structural-first, locale-neutral selectors (`download`, `2K`/`4K`); re-capture via spike |
+
+---
+
+## File structure
+
+### New files
+```
+src/gflow_cli/api/image_upscale.py        (or extend api/image.py)
+  UpsampleImageRequest frozen dataclass + TargetResolution enum (from_cli "2k"/"4k")
+tests/api/test_image_upscale.py
+  Unit tests: request build, response parse (cap/magic-byte/missing-field), 403 disambiguation
+tests/features/image_upscale.feature
+  BDD scenarios from /gflow:scenario (happy 2K, 4K-on-Pro, oversized, malformed mediaId)
+tests/features/test_image_upscale_steps.py
+  Step defs mirroring runtime signatures
+```
+
+### Modified files
+```
+src/gflow_cli/api/routes.py
+  + UPSAMPLE_IMAGE = f"{FLOW_API_BASE}/flow/upsampleImage"
+src/gflow_cli/api/client.py
+  + MAX_UPSAMPLE_B64_LEN; + async def upsample_image(media_id, target_resolution, out_path)
+    (mint reCAPTCHA via _mint_recaptcha_token; POST; cap+decode+magic-byte; write via image_output_path)
+src/gflow_cli/errors.py
+  + UpscaleUnavailableError (exit 22) registered in EXIT_CODE_MAP; distinct from WAF/reCAPTCHA 403
+src/gflow_cli/cli_image.py
+  + `upscale` Click command: <mediaId> arg, --scale Choice(['2k','4k']), --out, --profile
+src/gflow_cli/paths.py
+  (reuse image_output_path; add <mediaId>_<scale> naming if needed)
+docs/USAGE.md, README.md, docs/INDEX.md, CHANGELOG.md
+  document the command + the platform-only / Ultra-only constraints
+```
+
+---
+
+## Task 1 — Error type + exit code (test-first)
+
+**What:** Add `UpscaleUnavailableError` (exit 22) for tier-gated/permission failures, distinct from WAF/reCAPTCHA 403.
+
+**Files:**
+- `tests/test_errors.py` — assert exit code 22, EXIT_CODE_MAP registration, ordering invariant
+- `src/gflow_cli/errors.py` — new class + map entry
+
+**Steps:**
+- [x] Red test: `UpscaleUnavailableError` maps to 22; not equal to WAF 403 code
+- [x] Add the class (RFC 9457 fields: type/title/status/detail/remediation_hint) + register in `EXIT_CODE_MAP`
+- [x] Verify `test_exit_code_map_ordering_invariant` still passes (inheritance trap — see memory)
+
+**Tests created (red):**
+- [x] `test_upscale_unavailable_exit_code` — exit 22, distinct from WAF/reCAPTCHA
+
+---
+
+## Task 2 — Value objects (test-first)
+
+**What:** `TargetResolution` enum (`2K`/`4K` ↔ wire `UPSAMPLE_IMAGE_RESOLUTION_*`, `from_cli`) and frozen `UpsampleImageRequest`.
+
+**Files:**
+- `tests/api/test_image_upscale.py` — enum mapping, `from_cli` rejects bad values, request immutability
+- `src/gflow_cli/api/image.py` (or new `image_upscale.py`) — enum + dataclass + body builder
+
+**Steps:**
+- [x] Red tests: `TargetResolution.from_cli("2k")` → enum; `"1k"`/`"8k"` rejected; request frozen
+- [x] Add enum + `UpsampleImageRequest(media_id, target_resolution, recaptcha_token="")`
+- [x] Body builder → `{mediaId, targetResolution, clientContext:{recaptchaContext:{token}}}`
+- [x] mediaId UUID-allowlist validation (reject malformed before request)
+
+**Tests created (red):**
+- [x] `test_target_resolution_from_cli` / `test_target_resolution_rejects_1k_and_unknown`
+- [x] `test_upsample_request_body_shape`
+- [x] `test_media_id_uuid_validation`
+
+---
+
+## Task 3 — Client `upsample_image()` (test-first)
+
+**What:** Synchronous client method: mint reCAPTCHA, POST `upsampleImage`, parse `{encodedImage}` with cap + magic-byte, write file. Route constant added.
+
+**Files:**
+- `tests/api/test_image_upscale.py` — mocked transport/HTTP: happy path, oversized cap, missing field, non-image bytes, 403→typed error, no-retry on 4K 403, `encodedImage` never logged
+- `src/gflow_cli/api/routes.py` — `UPSAMPLE_IMAGE`
+- `src/gflow_cli/api/client.py` — `MAX_UPSAMPLE_B64_LEN = 50 * 1024 * 1024`; `upsample_image(...)`
+
+**Steps:**
+- [x] Red tests for: 200 happy (decode → PNG/JPEG bytes written); response > cap → typed error before decode; missing `encodedImage` → `WireFormatError` (redacted); decoded bytes fail magic-byte → typed error
+- [x] Red tests for 403 disambiguation: tier 403 → `UpscaleUnavailableError` (no retry); WAF 403 → existing `WafRejectionError`; expired-token 401 → existing refresh+single-retry
+- [x] Red test: structlog capture asserts `encodedImage` value never present in any event
+- [x] Add route + method; reuse `_mint_recaptcha_token("upscaleImage" or correct action)`; single Page checkout (no nested checkout — use `context.request` if aux call needed)
+- [x] Decode mirrors `concatenate_scene` (cap → `b64decode` → magic-byte → `del encoded`)
+- [x] Write via `paths.image_output_path` as `<mediaId>_<scale>.<ext>` (ext from magic byte)
+
+**Tests created (red):**
+- [x] `test_upsample_happy_2k`, `test_upsample_oversized_rejected`, `test_upsample_missing_field`,
+      `test_upsample_non_image_bytes`, `test_upsample_4k_pro_403_no_retry`,
+      `test_upsample_waf_403_distinct`, `test_upsample_encoded_image_never_logged`
+
+---
+
+## Task 4 — CLI surface (test-first)
+
+**What:** `gflow image upscale <mediaId> --scale 2k|4k [--out] [--profile]` with self-contained `--help`.
+
+**Files:**
+- `tests/test_cli_image.py` — Click invocation: arg/flag parsing, `--scale` Choice, exit codes, 4K/Pro hint, malformed mediaId usage error (no request), structlog `upscale_started/completed/unavailable`
+- `src/gflow_cli/cli_image.py` — `upscale` command
+
+**Steps:**
+- [x] Red tests: happy invocation calls `upsample_image` with mapped enum; `--scale 8k` rejected by Click; `--scale 1k` rejected with "1k is the original" hint; malformed mediaId → usage error, no HTTP
+- [x] Red test: 4K-on-Pro path surfaces exit 22 + Ultra-only remediation; no auto-retry
+- [x] Implement command; emit `upscale_started/completed/unavailable` (stable keys); `--help` states platform-only + Ultra-only constraints + "find mediaId via `gflow data list images`"
+- [x] Record the output asset via `OperationRecorder` honoring the redaction gate; wrap callback in try/except `DataStoreError`
+
+**Tests created (red):**
+- [x] `test_upscale_cli_happy`, `test_upscale_cli_scale_choice`, `test_upscale_cli_1k_rejected`,
+      `test_upscale_cli_bad_media_id`, `test_upscale_cli_4k_pro_exit22`
+
+---
+
+## Task 5 — BDD scaffold + green
+
+**What:** Gherkin feature covering all Critical+High scenarios; step defs mirror runtime signatures.
+
+**Files:**
+- `tests/features/image_upscale.feature` — happy 2K, 4K-on-Pro, oversized, malformed mediaId
+- `tests/features/test_image_upscale_steps.py` — typed step defs (mirror signatures — see memory)
+
+**Steps:**
+- [x] Add the four `/gflow:scenario` BDD scenarios as a feature file
+- [x] Implement step defs against the real command; assert exit codes + redaction
+- [x] All BDD green
+
+**Tests created:**
+- [x] BDD: 2K happy, 4K/Pro exit 22, oversized rejected, malformed mediaId usage error
+
+---
+
+## Task 6 — Docs + recon finalize
+
+**What:** User-facing docs + cross-references; recon already written.
+
+**Files:**
+- `docs/USAGE.md` — `gflow image upscale` section (workflow: `data list images` → `upscale`)
+- `README.md` command table; `docs/INDEX.md` route to `IMAGE_UPSCALE_RECON.md`
+- `docs/KNOWN_ISSUES.md` — note 4K Ultra-gating + per-profile WAF heat from the extra gated op
+- `CHANGELOG.md` `[Unreleased]` — `feat(image): upscale to 2K/4K (#171)`
+
+**Steps:**
+- [x] Write usage + constraints (platform-only, Ultra-only, credit-free expectation)
+- [x] Index the recon doc; cross-link spikes
+- [x] CHANGELOG entry referencing #171
+
+---
+
+## Task 7 — Full gates + PR
+
+**What:** Green `/gflow:check`; open PR to `develop`.
+
+**Steps:**
+- [x] `/gflow:check` green (ruff + format + `pyright src` + pytest ≥ 80% on changed dirs)
+- [x] Live smoke (opt-in, supervised): one real 2K upscale on a known mediaId (credit-free) confirms wire still matches
+- [x] PR `feature/image-upscale` → `develop`, `Closes #171`
+
+---
+
+## Definition of done
+
+- [x] All task steps checked off
+- [x] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [x] `CHANGELOG.md` `[Unreleased]` updated (`#171`)
+- [x] Docs updated (`USAGE.md`, `README.md`, `INDEX.md`, `KNOWN_ISSUES.md`)
+- [x] BDD feature covers all Critical + High scenarios from `/gflow:scenario`
+- [x] `encodedImage` proven absent from logs (test) — Critical mitigation verified
+- [x] 4K/Pro 403 → exit 22, no auto-retry — Critical mitigation verified
+- [x] No `# TODO` in diff without a tracked issue link