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

{gflow_cli-0.14.0 → gflow_cli-0.15.1}/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.14.0 → gflow_cli-0.15.1}/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`gflow image` can reference locked CHARACTER entities** for character-consistent
+  stills. New `--reference-entity <id>` (repeatable) + `--reference-entity-name` on
+  `image t2i` / `i2i`, plus `--project <id>` to generate in an EXISTING project (where
+  the entities live) instead of a throwaway scratch project. Entities attach through
+  the editor's **Personagens picker** and ride the submit as `referenceEntities`
+  (confirmed against the live API); `_build_batch_generate_images_body` serializes them
+  so non-UI/headless transports get parity too. Entities count toward the per-model
+  reference cap. `--project` / `--reference-entity` are single-prompt only; for a pure
+  character reference use `t2i` (`i2i` still needs a `--ref`). See `docs/USAGE.md` →
+  "Character-consistent images (entity references)".
+
+### Fixed
+
+- `--project` no longer overwrites an existing project's stored title/source in the
+  local history DB (the recorder preserves the curated title for non-created projects).
+
+### Security
+
+- `--project` / `--reference-entity` ids are validated at the CLI boundary
+  (`[A-Za-z0-9-]{1,128}`), closing an unvalidated `page.goto` navigation path
+  (`project_editor_url` lacked the allowlist its sibling routes enforce) and a
+  CSS-selector injection vector (`data-tile-id='fe_id_<id>'`). The request-body debug
+  logger elides large reference-field values so Flow-built image bytes can't leak into
+  logs.
+
+### Internal
+
+- Bump dev/CI `ruff` to `0.15.16` (both the `dev` extra and the `dependency-groups`
+  pin; supersedes Dependabot PR #165, which updated only the soft `>=` extra and not
+  the hard `==` group pin CI actually uses). `ruff check` / `format --check` clean.
+
 ## [0.14.0] — 2026-06-07
 
 ### Added
@@ -1434,7 +1484,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.14.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.15.1...HEAD
+[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
 [0.12.0]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...v0.12.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.14.0
+Version: 0.15.1
 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
@@ -53,7 +53,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.15.15; extra == 'dev'
+Requires-Dist: ruff>=0.15.16; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
@@ -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.14.0 → gflow_cli-0.15.1}/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.14.0 → gflow_cli-0.15.1}/docs/INDEX.md

@@ -37,6 +37,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[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 +55,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 +94,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 +109,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.14.0 → gflow_cli-0.15.1}/docs/PROJECT_STATUS.md

@@ -4,9 +4,9 @@
 
 ## Current release
 
-**v0.13.0 — alpha.** High-fidelity CLI hardening and term alignment. **`gflow video i2v`** now uses the canonical `--initial-frame` and `--end-frame` flags (matching Flow's UI labels), with robust Click greedy-fill protection and positional backward compatibility. **In-project governance** (ruff T20, materiality classification) is now active to harden the AI-driven development flow. This release also refactors the **`character_create` saga** for improved type safety and documentation. Live-verified end-to-end on 2026-06-04 with the new flags and interpolation paths.
+**v0.15.0 — alpha.** **Character-consistent images via entity references.** `gflow image t2i/i2i` can now reference locked Flow CHARACTER entities (`--reference-entity <id>`, repeatable) and generate in an existing project (`--project <id>`) where those entities live — entities attach through the editor's Personagens picker and ride the submit as `referenceEntities` (confirmed against the live API; the body builder serializes them for headless transports too). Live-verified 2026-06-08: a 3-frame Dragon-Hook smoke rendered drift-free with all three characters on-model. LLM-council-reviewed (security/correctness/dedup) before merge. Carries forward the v0.14.0 `gflow movie` line (multi-scene, character-consistent video).
 
-**Develop (unreleased, post-v0.13.0):** *(empty — develop is the staging branch for the next release).*
+**Develop (unreleased, post-v0.15.0):** *(empty — develop is the staging branch for the next release).*
 
 ## Milestone history
 
@@ -52,6 +52,8 @@
 | `gflow character rm` — free character deletion (#150) | ✅ done (v0.13.0) |
 | Align I2V CLI flags with Flow UI Labels (`--initial-frame`) (#122) | ✅ done (v0.13.0) |
 | In-project governance (ruff T20, materiality Classifier) | ✅ done (v0.13.0) |
+| `gflow movie` — multi-scene, character-consistent video from a TOML manifest (entity reuse, resumable, handoff manifest) | ✅ done (v0.14.0) |
+| `gflow image t2i/i2i` — reference locked CHARACTER entities (`--reference-entity`) + `--project` for character-consistent stills | ✅ done (v0.15.0) |
 | `gflow character` — reusable Flow Character entities (`create`/`list`/`show`/`voices`), persist-before-spend saga (#145) | ✅ done (v0.12.0) |
 | `gflow scene` — Add Clip / Scenes compose + credit-free server-side extended video (`runVideoFxConcatenation`) | ✅ done (v0.12.0) |
 | `gflow video chain` — last-frame I2V chaining from a JSONL manifest (`--dry-run`/`--max-links`/`--resume-from`) | ✅ done (v0.12.0) |

{gflow_cli-0.14.0 → gflow_cli-0.15.1}/docs/USAGE.md

@@ -131,6 +131,13 @@ Options:
                             Aspect ratio.                     [default: 9:16]
   -n, --count INTEGER       How many images to generate (1-4).  [default: 1]
   --out PATH                Output directory (see "Output paths" below).
+  --project ID              Generate in this EXISTING Flow project instead of a
+                            scratch project. Required to reference locked
+                            entities/assets in that project. Single-prompt only.
+  --reference-entity ID     Flow CHARACTER entity id to reference for character
+                            consistency (repeatable; must live in --project).
+                            Single-prompt only.
+  --reference-entity-name N Display name paired with --reference-entity.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -212,6 +219,10 @@ Options:
                             Aspect ratio.                     [default: 9:16]
   -n, --count INTEGER       How many images to generate (1-4).  [default: 1]
   --out PATH                Output directory (same semantics as t2i).
+  --project ID              Generate in this EXISTING Flow project (skip scratch).
+  --reference-entity ID     Flow CHARACTER entity id to reference (repeatable;
+                            must live in --project). Counts toward the ref cap.
+  --reference-entity-name N Display name paired with --reference-entity.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -248,6 +259,40 @@ A 2-image run produces files numbered `_1.png`, `_2.png`:
 ./variants/<media_name_b>_2.png
 ```
 
+## Character-consistent images (entity references)
+
+`--reference-entity` makes `image t2i`/`i2i` reference a locked Flow **CHARACTER
+entity** (minted via `gflow character create`) so the generated subject stays
+on-model across shots — no per-shot prompt wrangling or fragile image refs.
+
+How it works: entities are **project-scoped**, so you must generate **in the
+project that owns them** via `--project <id>` (this also means no throwaway
+scratch project is created). The CLI attaches each entity through the Flow editor's
+resource picker; the submit then carries `referenceEntities`, exactly like the
+video R2V path. Entities count toward the same per-model reference cap as `--ref`
+images. `--reference-entity` / `--project` are **single-prompt only**.
+
+For a *pure* character reference (no starting image) use `t2i` — `i2i` still
+requires at least one `--ref`.
+
+```bash
+# One locked character, consistent across runs (t2i = no image ref needed)
+gflow image t2i "Aria explores a neon market, full body" \
+  --project 7fa97443-… --reference-entity 8a77f8cb-… --reference-entity-name Aria \
+  --model nano2 --aspect 9:16 -n 3
+
+# Several characters in one scene (each --reference-entity repeatable)
+gflow image t2i "Aria and Drako meet at the gate" --project 7fa97443-… \
+  --reference-entity 8a77f8cb-… --reference-entity 4ed5cb7f-…
+
+# i2i: a starting image PLUS an entity for the character
+gflow image i2i "place this hero in a snowy pass" --ref hero.png \
+  --project 7fa97443-… --reference-entity 8a77f8cb-…
+```
+
+> Ids are validated at the CLI boundary (letters/digits/hyphens, ≤128 chars).
+> The entity must already exist in `--project` (see `gflow character create`).
+
 ## `gflow image batch`
 
 Generate multiple images from a single manifest file. The format is dispatched by file extension (`.json` or `.tsv`).

{gflow_cli-0.14.0 → gflow_cli-0.15.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.14.0"
+version = "0.15.1"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -33,7 +33,7 @@ dependencies = [
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",
-    "ruff>=0.15.15",
+    "ruff>=0.15.16",
     "pyright>=1.1.0",
     # video-chain: the last-frame extractor (media.py) decodes with PyAV, and its
     # tests build synthetic mp4 fixtures with numpy. Declared here so the dev/CI
@@ -134,7 +134,7 @@ dev = [
     "pytest-asyncio>=1.3.0",
     "pytest-bdd>=8.1.0",
     "pytest-cov>=7.1.0",
-    "ruff==0.15.15",
+    "ruff==0.15.16",
 ]
 # Container-based integration tests — requires Docker daemon.
 # Install: uv sync --group containers

gflow_cli-0.15.1/scripts/diag/README.md

@@ -0,0 +1,29 @@
+# scripts/diag/ — Diagnostic Investigation Scripts
+
+These scripts require a live authenticated Chrome profile to run. They are investigation tools — not CI gates and not developer workflow tools — that help answer "what does this system actually do?" questions by observing a real browser session. Each script produces human-readable or structured output and does not modify production state.
+
+## Scripts
+
+| Script | Purpose | Prerequisite | Run |
+|---|---|---|---|
+| `capture_flow_traffic.py` | Capture Flow's outgoing API requests via `page.route` | `gflow auth login` | `uv run python scripts/diag/capture_flow_traffic.py --profile NAME` |
+| `recaptcha_mint.py` | What `site_key` + token does gflow-cli's `TokenMinter` produce? | `gflow auth login` (headed) | `uv run python scripts/diag/recaptcha_mint.py --profile NAME` |
+| `memory_profile.py` | Chrome process-tree RSS at key milestones (issue #155) | `gflow auth login` + `pip install psutil` | `uv run python scripts/diag/memory_profile.py --profile NAME` |
+
+## What belongs here
+
+1. Requires a live authenticated session to run
+2. Produces human-readable or structured output for investigation
+3. Does not write to production data stores
+4. Answers a specific "what does this system actually do?" question
+
+## What does NOT belong here
+
+- **CI gates** → `scripts/ci/` (run on every commit, no auth needed)
+- **Developer workflow tools** → `scripts/dev/` (`active_plan.py`, `skillopt/`, etc.)
+- **Live smoke tests** → `scripts/` root (`smoke_*.py` — full end-to-end generation runs)
+
+## Platform notes
+
+- `memory_profile.py` requires `psutil`: `uv add --dev psutil` (not a hard dep — detected at runtime)
+- All scripts: `uv run python scripts/diag/<name>.py` (no global Python install needed)

gflow_cli-0.14.0/scripts/diag_capture_flow_traffic.py → gflow_cli-0.15.1/scripts/diag/capture_flow_traffic.py

@@ -4,7 +4,7 @@ Spec § 11 mentioned a captured wire sample (samples/captured/06_batchGenerateIm
 but the file doesn't exist. This script produces that ground truth — what
 headers does Flow's UI actually attach when it calls aisandbox-pa?
 
-Run: `uv run python scripts/diag_capture_flow_traffic.py --profile <your-profile>`
+Run: `uv run python scripts/diag/capture_flow_traffic.py --profile <your-profile>`
 
 Output goes to `tmp/captured/flow_outgoing_<utc>.jsonl` by default. **NEVER write
 captured traffic to `samples/captured/`** — those files contain live Bearer tokens

gflow_cli-0.15.1/scripts/diag/memory_profile.py

@@ -0,0 +1,235 @@
+"""Diagnostic — Chrome process-tree RSS at key milestones (issue #155).
+
+Measures how much memory the Chrome/Chromium process tree consumes at four
+points during a real browser launch against a gflow-cli profile:
+
+  baseline        — before Playwright starts (current Python process only)
+  post_launch     — immediately after launch_persistent_context returns
+  post_navigation — after page.goto(FLOW_URL, wait_until="networkidle")
+  post_close      — after context.close() and Playwright stop
+
+The output table shows Own RSS (the profiler's Python process) and Tree RSS
+(profiler + all Chrome child processes) so you can see exactly how much RAM
+Chrome adds at each stage.
+
+Run: `uv run python scripts/diag/memory_profile.py --profile NAME [--output-json PATH]`
+
+Prerequisite: gflow auth login (plus psutil — install with: uv add --dev psutil)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+try:
+    import psutil
+except ImportError:
+    print("psutil is required: uv add --dev psutil", file=sys.stderr)
+    sys.exit(2)
+
+try:
+    from gflow_cli.api.transports.ui_automation import FLOW_URL
+except ImportError:
+    FLOW_URL = "https://labs.google/fx/tools/flow?hl=en"
+
+from playwright.async_api import async_playwright
+
+from gflow_cli.auth import profile_dir
+from gflow_cli.browser_manager import channel_for_profile
+from gflow_cli.config import get_settings
+
+CHROME_ARGS = [
+    "--disable-blink-features=AutomationControlled",
+    "--disable-dev-shm-usage",
+]
+
+_COL_MILESTONE = 16
+_COL_OWN = 14
+_COL_TREE = 15
+_COL_DELTA = 12
+
+
+def _tree_rss_mb(pid: int) -> float:
+    """Return total RSS (MB) of a process and all its descendants."""
+    try:
+        proc = psutil.Process(pid)
+        procs = [proc, *proc.children(recursive=True)]
+        return sum(p.memory_info().rss for p in procs if p.is_running()) / (1024 * 1024)
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        return 0.0
+
+
+def _own_rss_mb() -> float:
+    """Return RSS (MB) of only the current Python process."""
+    try:
+        return psutil.Process(os.getpid()).memory_info().rss / (1024 * 1024)
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        return 0.0
+
+
+def _print_table_header() -> None:
+    header = (
+        f"{'Milestone':<{_COL_MILESTONE}} | "
+        f"{'Own RSS (MB)':>{_COL_OWN}} | "
+        f"{'Tree RSS (MB)':>{_COL_TREE}} | "
+        f"{'Delta (MB)':>{_COL_DELTA}}"
+    )
+    sep = "-" * len(header)
+    print(sep)
+    print(header)
+    print(sep)
+
+
+def _print_table_row(name: str, own_mb: float, tree_mb: float, delta: float | None) -> None:
+    delta_str = "—" if delta is None else f"{delta:+.1f}"
+    print(
+        f"{name:<{_COL_MILESTONE}} | "
+        f"{own_mb:>{_COL_OWN}.1f} | "
+        f"{tree_mb:>{_COL_TREE}.1f} | "
+        f"{delta_str:>{_COL_DELTA}}"
+    )
+
+
+async def run(profile_name: str, output_json: Path | None) -> None:
+    """Main diagnostic loop."""
+    # Resolve profile directory using GFLOW_CLI_HOME
+    settings = get_settings()
+    _ = settings.home  # ensure settings loaded; profile_dir() uses get_settings() internally
+    pdir = profile_dir(profile_name)
+    if not pdir.exists():
+        print(f"ERROR: Profile directory not found: {pdir}", file=sys.stderr)
+        sys.exit(1)
+
+    milestones: list[dict[str, object]] = []
+    pid = os.getpid()
+
+    # -------------------------------------------------------------------------
+    # Milestone 1: baseline (before Playwright starts)
+    # -------------------------------------------------------------------------
+    own_baseline = _own_rss_mb()
+    tree_baseline = _tree_rss_mb(pid)
+    milestones.append(
+        {
+            "name": "baseline",
+            "own_rss_mb": round(own_baseline, 2),
+            "tree_rss_mb": round(tree_baseline, 2),
+            "delta_mb": None,
+        }
+    )
+
+    _print_table_header()
+    _print_table_row("baseline", own_baseline, tree_baseline, None)
+
+    channel = channel_for_profile(pdir)
+
+    async with async_playwright() as pw:
+        launcher = pw.chromium
+
+        # -------------------------------------------------------------------------
+        # Milestone 2: post_launch
+        # -------------------------------------------------------------------------
+        ctx = await launcher.launch_persistent_context(
+            str(pdir),
+            headless=False,
+            args=CHROME_ARGS,
+            locale="en-US",
+            **({"channel": channel} if channel else {}),
+        )
+
+        own_post_launch = _own_rss_mb()
+        tree_post_launch = _tree_rss_mb(pid)
+        delta_launch = tree_post_launch - tree_baseline
+        milestones.append(
+            {
+                "name": "post_launch",
+                "own_rss_mb": round(own_post_launch, 2),
+                "tree_rss_mb": round(tree_post_launch, 2),
+                "delta_mb": round(delta_launch, 2),
+            }
+        )
+        _print_table_row("post_launch", own_post_launch, tree_post_launch, delta_launch)
+
+        # -------------------------------------------------------------------------
+        # Milestone 3: post_navigation
+        # -------------------------------------------------------------------------
+        page = ctx.pages[0] if ctx.pages else await ctx.new_page()
+        print(f"Navigating to {FLOW_URL} ...")
+        try:
+            await page.goto(FLOW_URL, wait_until="networkidle", timeout=45_000)
+        except Exception as exc:  # noqa: BLE001
+            print(f"WARNING: navigation did not fully settle: {exc}", file=sys.stderr)
+
+        own_post_nav = _own_rss_mb()
+        tree_post_nav = _tree_rss_mb(pid)
+        delta_nav = tree_post_nav - tree_baseline
+        milestones.append(
+            {
+                "name": "post_navigation",
+                "own_rss_mb": round(own_post_nav, 2),
+                "tree_rss_mb": round(tree_post_nav, 2),
+                "delta_mb": round(delta_nav, 2),
+            }
+        )
+        _print_table_row("post_navigation", own_post_nav, tree_post_nav, delta_nav)
+
+        # -------------------------------------------------------------------------
+        # Milestone 4: post_close
+        # -------------------------------------------------------------------------
+        await ctx.close()
+
+    own_post_close = _own_rss_mb()
+    tree_post_close = _tree_rss_mb(pid)
+    delta_close = tree_post_close - tree_baseline
+    milestones.append(
+        {
+            "name": "post_close",
+            "own_rss_mb": round(own_post_close, 2),
+            "tree_rss_mb": round(tree_post_close, 2),
+            "delta_mb": round(delta_close, 2),
+        }
+    )
+    _print_table_row("post_close", own_post_close, tree_post_close, delta_close)
+    print("-" * (_COL_MILESTONE + _COL_OWN + _COL_TREE + _COL_DELTA + 9))
+
+    # -------------------------------------------------------------------------
+    # JSON output (optional)
+    # -------------------------------------------------------------------------
+    if output_json is not None:
+        result = {
+            "platform": sys.platform,
+            "chrome_args": CHROME_ARGS,
+            "milestones": milestones,
+        }
+        output_json.parent.mkdir(parents=True, exist_ok=True)
+        output_json.write_text(json.dumps(result, indent=2), encoding="utf-8")
+        print(f"JSON written to: {output_json}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--profile",
+        required=True,
+        help="Name of the gflow-cli profile (directory under GFLOW_CLI_HOME)",
+    )
+    parser.add_argument(
+        "--output-json",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Optional path to write machine-readable results as JSON",
+    )
+    args = parser.parse_args()
+    asyncio.run(run(args.profile, args.output_json))
+
+
+if __name__ == "__main__":
+    main()

gflow_cli-0.14.0/scripts/diag_recaptcha_mint.py → gflow_cli-0.15.1/scripts/diag/recaptcha_mint.py

@@ -1,6 +1,6 @@
 """Diagnostic — what site_key + token does gflow-cli's TokenMinter produce?
 
-Run: `uv run python scripts/diag_recaptcha_mint.py --profile <your-profile>`
+Run: `uv run python scripts/diag/recaptcha_mint.py --profile <your-profile>`
 
 Opens HEADED Chromium, navigates to Flow, runs TokenMinter, prints the
 discovered site_key + minted token length. Compare to HAR ground truth:

{gflow_cli-0.14.0 → gflow_cli-0.15.1}/src/gflow_cli/__init__.py

@@ -1,3 +1,3 @@
 """gflow-cli — unofficial CLI for Google Flow."""
 
-__version__ = "0.14.0"
+__version__ = "0.15.1"

{gflow_cli-0.14.0 → gflow_cli-0.15.1}/src/gflow_cli/api/client.py

@@ -293,7 +293,7 @@ class FlowApiClient:
                 "--no-sandbox",
                 "--password-store=basic",
             ],
-            "args": ["--disable-blink-features=AutomationControlled"],
+            "args": ["--disable-blink-features=AutomationControlled", "--disable-dev-shm-usage"],
         }
 
     async def _enter_setup(self) -> None: