gflow-cli 0.43.0__tar.gz → 0.45.0__tar.gz

gflow_cli-0.45.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "gflow-cli",
+  "interface": {
+    "displayName": "gflow-cli"
+  },
+  "plugins": [
+    {
+      "name": "gflow",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

gflow_cli-0.45.0/.codex-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "gflow",
+  "version": "0.45.0",
+  "description": "Reusable development and operations workflows for gflow-cli",
+  "author": {
+    "name": "Flavio Oliva",
+    "url": "https://github.com/ffroliva"
+  },
+  "homepage": "https://github.com/ffroliva/gflow-cli",
+  "repository": "https://github.com/ffroliva/gflow-cli",
+  "license": "MIT",
+  "keywords": [
+    "gflow-cli",
+    "codex",
+    "google-flow"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "gflow-cli",
+    "shortDescription": "Develop, validate, review, and operate gflow-cli.",
+    "longDescription": "Project workflows for planning, validation, issue handling, reviews, releases, and Google Flow CLI operations.",
+    "developerName": "Flavio Oliva",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/ffroliva/gflow-cli",
+    "defaultPrompt": [
+      "Show the current gflow-cli task with $gflow:status.",
+      "Run the gflow-cli quality gates with $gflow:check."
+    ]
+  }
+}

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/.pre-commit-config.yaml

@@ -23,8 +23,10 @@
 default_stages: [pre-commit]
 
 repos:
+  # Keep this rev in lockstep with the `ruff==` pin in pyproject.toml. A hook that
+  # formats with an older ruff than CI checks with will fight CI on every commit.
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.10
+    rev: v0.16.0
     hooks:
       - id: ruff
         args: [--fix]

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/AGENTS.md

@@ -81,6 +81,23 @@ These rules exist because docs alone don't bind under momentum: a "check open PR
 - **If a claim can't be verified in the current environment, it's LIKELY — not CONFIRMED.** Keep the issue open, reference it with `Refs #N` (not `Closes #N`), and ship diagnostics rather than a blind fix. When you can't reproduce it, hand the fix to whoever can.
 - **This project reverse-engineers a blackbox.** gflow-cli doesn't own Google Flow — it drives real Flow through inspected HAR/DOM/browser-log behavior. Offline checks (types, lint, unit/BDD tests) verify *our* code does what we think it does; they cannot verify Flow still behaves the way we captured it. Every feature that touches a generation path is **live-verified**, not just offline-tested, before it's called done — see `/gflow:live-verify`.
 
+## Standard Workflow Sequence
+
+All AI agents and harnesses working on `gflow-cli` follow this standard 10-phase pipeline from issue discovery to public release:
+
+| Phase | Skill / Command | Purpose | Output Artifact |
+|---|---|---|---|
+| 1. Triage | `/gflow:issue-assessment <N>` | Read-only issue analysis & root cause hypothesis | `issue_assessment_<N>.md` |
+| 2. Pre-Implementation | `/gflow:predict <proposal>` | Adversarial audit (D14 YAGNI, security, risks) | GO / CAUTION / STOP verdict |
+| 3. BDD Scaffolding | `/gflow:scenario <feature>` | Edge-case explorer & BDD Gherkin spec | `Scenario:` blocks & test scaffold |
+| 4. Implementation Plan | `/gflow:plan <feature>` | Task-by-task atomic implementation plan | `docs/superpowers/plans/<date>-<slug>/PLAN.md` |
+| 5. Council Review | `/gflow:pr-council-review` / `llm-council` | Multi-dimensional audit across 6 core dimensions | Consensus verdict report |
+| 6. Task Execution | `/gflow:status` | Track unchecked tasks during TDD execution | Next unchecked task |
+| 7. Pre-Commit Quality | `/gflow:check` | The Impeccable Routine (hygiene, ruff, pyright, pytest) | All green local checks |
+| 8. Live Verification | `/gflow:live-verify` | 5-layer proof against real Flow transport | `docs/LIVE_VERIFICATION_vX.Y.Z.md` |
+| 9. PR & Issue Close | `/gflow:issue-resolve <N>` | PR, SonarCloud 0-issue gate, merge to develop | Closed GitHub issue |
+| 10. Release Pipeline | `/gflow:release` | Version bump, signed tag (`git tag -s`), PyPI publish | Shipped release & back-merge |
+
 ## Skills reference (cross-tool)
 
 The `skills/` directory ships installable agent skill docs in plain Markdown with YAML frontmatter. Any agent can consume them directly:
@@ -109,7 +126,21 @@ and must be resolvable by ANY agent via this file. Vendor directories hold thin
 only (`.claude/commands/gflow/*.md` are pointers into `skills/`); never put protocol
 content in a vendor directory.
 
-**Cursor / Aider / Codex / Antigravity (`agy`):** paste or include the relevant `SKILL.md` in your system context. Note: in the `agy` TUI prompt, custom slash commands (e.g. `/gflow:pr-council-review`) are blocked by the TUI's command parser. Type them as plain text without the leading slash (e.g. `gflow:pr-council-review`, `gflow:branch-review`, or `gflow:check`) to trigger the corresponding agent skill workflow.
+**Codex CLI / desktop app:** install the repo's skills-only plugin from the repository root,
+then start a new session:
+
+```powershell
+codex plugin marketplace add .
+codex plugin add gflow@gflow-cli
+```
+
+Invoke skills with Codex's `$` syntax, for example `$gflow:status`, `$gflow:check`, or
+`$gflow:pr-council-review`. Codex reserves slash commands for its own command surface; the
+Claude Code spelling `/gflow:*` is therefore intentionally not reproduced. The Codex IDE
+extension does not currently load plugins, so IDE-only users should include the relevant
+`skills/<name>/SKILL.md` directly.
+
+**Cursor / Aider / Antigravity (`agy`):** paste or include the relevant `SKILL.md` in your system context. Note: in the `agy` TUI prompt, custom slash commands (e.g. `/gflow:pr-council-review`) are blocked by the TUI's command parser. Type them as plain text without the leading slash (e.g. `gflow:pr-council-review`, `gflow:branch-review`, or `gflow:check`) to trigger the corresponding agent skill workflow.
 **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.
 

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/CHANGELOG.md

@@ -7,6 +7,140 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.45.0] — 2026-07-28
+
+### Fixed
+
+- **`gflow character create` binds portraits to the character again (#395).**
+  Two independent defects made every character generation land as a plain
+  project image, leaving the character empty:
+  1. **Overlay dismissal Escaped Flow's own UI.** `[role='dialog']` and
+     `[role='alert']` had been added to the overlay detector, but Flow's
+     character composer (and the media picker) carry those roles — so gflow
+     pressed Escape on the app itself, the generation went out without
+     `entityContext`, and Flow filed the image against the project with no
+     `parentEntityId`. Those two selectors are removed; `[role='banner']` and
+     the announcement matcher remain, so the original banner-dismissal intent
+     is intact.
+  2. **The character route could bounce back to the project page.** Flow
+     redirects `/project/{id}/character/{entityId}` when the entity is not yet
+     queryable — a race gflow loses by navigating immediately after
+     `flow.createEntity`. Because the project page also mounts a prompt box,
+     the old readiness check was satisfied on the wrong surface and the prompt
+     was typed into the **project** composer. gflow now verifies it actually
+     came to rest on the character route, re-navigating a few times and failing
+     loudly rather than generating on the wrong surface.
+
+  Verified live 2026-07-28 in both directions on the same account, plus a
+  read-back showing the character carrying its name and `thumbnail_media_id`.
+  The wire contract is documented in
+  [CHARACTER_RECON](docs/CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+
+- **`gflow image i2i --ref <UUID>` no longer fails when the asset is out of the
+  picker's reach (#393).** Flow's media picker is scoped to the active project
+  and its search does **not** index media UUIDs (confirmed live 2026-07-27:
+  both UUID search tiers returned zero tiles), so a `--ref` pointing at an asset
+  in another project — or buried deep in a virtualised grid — could not be
+  selected, and a bare `--ref <uuid>` carried no local file to fall back on. The
+  CLI now resolves each UUID ref against the local catalog and attaches its
+  recorded file, so the transport uploads those exact bytes instead of failing
+  the run. Verified live as a controlled A/B on identical input: exit 9 before,
+  exit 0 with the upload fallback after. Enrichment is best-effort (unknown
+  asset, unavailable catalog, or deleted file leaves the ref untouched) and the
+  **fail-loud contract is unchanged** — a reference that cannot be bound still
+  aborts the generation rather than silently producing an unreferenced image.
+- **A Flow web-app crash on the character-editor route is now reported as
+  such.** `gflow character create` surfaced Flow's client-side crash as
+  `RuntimeError: Character editor not ready: prompt textbox not visible`, which
+  blames a selector that was never on the page. The existing crash classifier is
+  now consulted at that gate too, yielding the typed, retryable `FlowAppError`
+  (exit 31). Observed live 2026-07-27 via the incident bundle's `ui.json`
+  (`title.category: flow_app_crash`).
+- **Character binding failures say what actually happened.** When Flow returns a
+  workflow that is not bound to the character entity, the error read "Unexpected
+  response shape from Flow", sending readers after a wire-format bug. It now
+  states that Flow filed the image as a plain project image and the character
+  has no portrait. The guard remains strict — verified live that unbound runs
+  leave the entity as "Untitled Character" with a null thumbnail.
+- **Tier-aware credit confirmations:** `gflow video chain` and `gflow movie run`
+  no longer present pending work as an exact one-credit-per-link/scene charge.
+  Plans, confirmation prompts, `--dry-run` output, Click help, and current docs
+  now report the count of *pending video operations* and direct operators to
+  Google Flow for current model/duration/tier pricing, which varies by account
+  tier and Flow policy. Execution, resume/stale accounting, `--yes`, JSON
+  output, flags, and exit codes are unchanged.
+
+### Added
+
+- **Top Banner & Modal Dismissal (#369):** Expanded `_detect_overlay` and
+  `_dismiss_blocking_overlays` in `ui_automation.py` to detect top banners,
+  alert bars, and announcement dialogs (`[role='banner']`, `[role='alert']`,
+  `[role='dialog']`, `div:has-text('What\'s new')`), force-clicking locale-stable
+  close/clear/Got-it buttons and falling back to Escape before automation tasks.
+- **`gflow character create --format-prompt` (#383):** Opt-in flag that clicks
+  Flow's in-editor **Format** button before submitting, letting Flow rewrite the
+  prompt into its character prompt-engineering shape. Applies to both the face and
+  body slots. Best-effort by design — if the button is not found the prompt is
+  submitted as typed rather than failing the generation. The selector cascade is
+  anchored on the locale-stable `personal_recommendations` Material Symbols
+  ligature (confirmed against live DOM 2026-07-27), not the "Format" label, which
+  Flow localises to the Chrome profile language. Flow ships the button `disabled`
+  on an empty prompt, so the driver checks enabled-ness — a disabled button is
+  still *visible*, and clicking one would stall on Playwright's actionability wait.
+- **Self-documenting error remediation & provider message pass-through (#380):** Added default `remediation_hint` strings across domain exception classes (`WireFormatError`, `ContentPolicyError`, `RateLimitError`, `DataStoreError`, `SceneConcatError`, `FrameExtractionError`), extracted and sanitized provider error messages from Google Flow tRPC/REST responses, and enriched MCP tool error envelopes and Rich CLI error displays with actionable recovery guidance at failure time.
+
+## [0.44.0] — 2026-07-26
+
+### Added
+
+- **Dual-Side Project Naming & Management (`gflow project`)** (#381). Added
+  `gflow project` subcommand group (`list`, `show`, `rename`, `create`),
+  `--project-name` / `--project-title` options across `gflow image` and `gflow video`
+  generation commands, prompt slugging for scratch projects, and dual-side title sync
+  updating Google Flow's tRPC server/UI and local SQLite catalog in lockstep.
+- **Namespaced Codex project skills.** The canonical workflows under `skills/`
+  now ship as a repo-local, skills-only Codex plugin. Register and install it
+  with `codex plugin marketplace add .` followed by
+  `codex plugin add gflow@gflow-cli`, then invoke workflows such as
+  `$gflow:status`, `$gflow:check`, and `$gflow:pr-council-review` in a new
+  Codex CLI or desktop-app session. Claude Code's `/gflow:*` commands and the
+  agent-agnostic skill files remain unchanged.
+- **`gflow data errors` — bounded retention + export for failed-operation
+  history** (#345). `gflow data errors export [--older-than AGE] [-o FILE]`
+  dumps failed operations as JSONL (unbounded, newest-first) for offline
+  archival — also closing the export path deferred from #341. `gflow data
+  errors prune --older-than AGE [--dry-run]` deletes failures older than AGE
+  (`90d` / `24h` / `30m`); `--older-than` is **required** and there is no
+  automatic/background pruning — deletion is always an explicit operator
+  action. Both honor `--profile` and the exit-16 `DataStoreError` convention.
+
+### Fixed
+
+- **`gflow character create` safely activates the current Create-Body
+  composer.** Flow can autosave the body triptych over the stored portrait
+  prompt when the mode switch has not settled (observed live 2026-07-25 on
+  0.43.0). Current Flow reuses one Slate editor and exposes Create Body through
+  the locale-independent `accessibility_new` icon beside the portrait image;
+  gflow now clicks that scoped mode control, requires a new generated-face
+  reference chip to mount, and verifies the shared editor owns focus **before
+  any clearing or typing**. Readback failures abort before submit. The older
+  `add_2`/second-box cohort remains supported through its count-rise gate.
+  Post-type isolation still aborts before the credited submit. Live DOM
+  evidence and the one-box failure were captured on 2026-07-26. Face-only
+  creates are unchanged.
+
+- **Profile-lock remediation message** now names the real cause and recovery.
+  `ProfileLockedError` (exit 11) previously told operators to "wait for it to
+  finish" — implying an unbounded wait — and to hunt for a `gflow`/Chrome
+  process. In practice a blocking lock is a kernel *advisory* lock held by a
+  **live** process (often a `python.exe` a `chrome.exe` scan misses); the OS
+  releases it the instant the holder dies, so a leftover lock *file* never
+  blocks acquisition. The message now points to the recorded owner PID
+  (surfaced locally since v0.43.0) and says to just retry when nothing is
+  running. The lock itself is unchanged — auto-reclaim was considered and
+  rejected as unsafe (an unlink→new-inode race could put two browsers on one
+  profile, the exact corruption the lease prevents). Refs #370.
+
 ## [0.43.0] — 2026-07-23
 
 ### Added
@@ -2332,7 +2466,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.43.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.45.0...HEAD
+[0.45.0]: https://github.com/ffroliva/gflow-cli/compare/v0.44.0...v0.45.0
+[0.44.0]: https://github.com/ffroliva/gflow-cli/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/ffroliva/gflow-cli/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/ffroliva/gflow-cli/compare/v0.41.0...v0.42.0
 [0.41.0]: https://github.com/ffroliva/gflow-cli/compare/v0.40.0...v0.41.0

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/CONTRIBUTING.md

@@ -11,6 +11,22 @@ uv sync --extra dev
 uv run playwright install chromium
 ```
 
+### Codex project skills
+
+Codex CLI and the Codex desktop app can install the repository's canonical `skills/`
+workflows as the `gflow` plugin. From the repository root, run:
+
+```bash
+codex plugin marketplace add .
+codex plugin add gflow@gflow-cli
+```
+
+Start a new Codex session after installation, then invoke a workflow with `$gflow:<skill>`
+(for example, `$gflow:status`, `$gflow:check`, or `$gflow:pr-council-review`). Claude Code
+continues to use the equivalent `/gflow:*` commands. The Codex IDE extension does not
+currently load plugins; include the relevant `skills/<name>/SKILL.md` directly when using
+that surface.
+
 ## Test-driven development (mandatory)
 
 `gflow-cli` is built test-first. Every change must include tests, and CI rejects PRs that lower coverage.

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/KNOWN_ISSUES.md

@@ -31,22 +31,27 @@ targeted dismissal once the next occurrence is captured. **Workaround:**
 re-run the command; open the project once manually in Chrome to consume the
 banner.
 
-### Reported stale profile lock blocks acquisition (unreproduced)
-
-- **Status:** Open ([#370](https://github.com/ffroliva/gflow-cli/issues/370))
-- **Severity:** Medium (blocks the profile until resolved) · **Affected:** `ProfileLease` acquisition (exit 11)
-
-A user report of `ProfileLockedError` with no apparently-live owner. Not
-reproduced: in every observed case the kernel advisory lock was held by a
-real process (e.g. a pytest child that outlived its parent shell). The
-kernel lock is authoritative — a merely *stale metadata file* cannot block
-acquisition, and gflow will never auto-delete a lock file or kill a
-recorded PID based on metadata. Since v0.43.0, contention reports the
-recorded owner's PID and observed start time locally (lock-file metadata
-now starts at offset 1 so Windows contenders can read it while byte 0 is
-kernel-locked), and a metadata-only incident bundle is written before any
-Chrome launch. **Workaround:** find and close the owning process (the
-error's local output names its PID), or use a different `--profile`.
+### Profile lock reported as "held by another process" with no obvious owner
+
+- **Status:** Resolved ([#370](https://github.com/ffroliva/gflow-cli/issues/370)) · remediation message clarified
+- **Severity:** Low (by design; fails closed — never corrupts) · **Affected:** `ProfileLease` acquisition (exit 11)
+
+`ProfileLockedError` can surface when no `chrome.exe` / `gflow` process is
+obvious. This is **working as intended, not a stale-file bug.** The profile
+lock is a kernel *advisory* byte-range lock, which the OS releases the instant
+its holder dies — so a leftover lock *file* can never block acquisition. If
+`acquire` is blocked, a **live** process genuinely holds it, most often a
+`python.exe` (a prior gflow run, or a pytest child that outlived its shell)
+that a scan for `chrome.exe` misses. gflow deliberately never auto-deletes a
+lock file or kills a recorded PID from metadata: an unlink→new-inode race could
+put two browsers on one profile — the exact corruption the lease exists to
+prevent. Since v0.43.0 contention reports the recorded owner's PID and observed
+start time locally (metadata starts at offset 1 so Windows contenders can read
+it while byte 0 is kernel-locked), and the remediation message now names the
+live-owner reality and tells you to just retry when nothing is running.
+**Workaround:** close the process at the PID the error prints
+(`Get-Process -Id <pid>` / `ps -p <pid>`, then `Stop-Process -Id <pid>` /
+`kill <pid>`), or use a different `--profile`.
 
 ### Unexplained image-generation HTTP 400 (observed live 2026-07-22)
 
@@ -819,6 +824,34 @@ gflow image batch ./batch-b.tsv --profile personal
 
 ## Resolved
 
+### `character create` generated portraits that never bound to the character — RESOLVED in v0.45.0
+
+- **Status:** Resolved ([#395](https://github.com/ffroliva/gflow-cli/issues/395)) · **Severity:** Was-High · **Was-affecting:** v0.44.0 and unreleased `develop` · **Fixed in:** v0.45.0
+
+Every `gflow character create` spent an Imagen credit, produced an image, and
+left the character empty ("Untitled Character", null thumbnail). Flow filed the
+generation as an ordinary project image because the request carried no
+`entityContext`. Two independent gflow defects caused it:
+
+1. **Overlay dismissal Escaped Flow's own UI.** `[role='dialog']` and
+   `[role='alert']` had been added to the overlay detector, but Flow's character
+   composer — and the media picker — carry those roles. gflow pressed Escape on
+   the app itself and the submit lost its entity context.
+2. **The character route could bounce to the project page.** Flow redirects
+   `/project/{id}/character/{entityId}` while the entity is not yet queryable
+   (gflow navigates immediately after `flow.createEntity`). The project page
+   also mounts a prompt box, so the readiness gate passed on the wrong surface
+   and the prompt was typed into the **project** composer.
+
+Both are fixed: the two over-broad selectors are gone (banner detection intact),
+and the transport now verifies it came to rest on the character route,
+re-navigating and then failing loudly instead of generating on the wrong
+surface. The `parentEntityId` guard that surfaced this was correct throughout —
+it refused to report a portrait-less character as success.
+
+Wire contract: [CHARACTER_RECON § entity binding](docs/CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+Evidence: [LIVE_VERIFICATION_v0.45.0 §2](docs/LIVE_VERIFICATION_v0.45.0.md).
+
 ### `gflow video`'s manifest-driven batch subcommand didn't skip already-completed entries — RESOLVED as obsolete
 
 - **Status:** Resolved (obsolete) · **Severity:** Was-Medium · **Was-affecting:** v0.2.0a1 through the command's removal · **Fixed in:** n/a — removed in production-readiness hardening (see `fix: remove nonfunctional video batch command`)

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.43.0
+Version: 0.45.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
@@ -58,7 +58,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.22; extra == 'dev'
+Requires-Dist: ruff==0.16.0; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/RELEASE.md

@@ -85,13 +85,14 @@ python -m pip install --pre gflow-cli
    see the root-doc allowlist.)
 6. Update the version in:
    - `pyproject.toml`
+   - `.codex-plugin/plugin.json`
    - `src/gflow_cli/__init__.py`
    - any tests that assert the package version
 7. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
    release section.
 8. Commit the release prep:
    ```bash
-   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests docs
+   git add pyproject.toml .codex-plugin/plugin.json src/gflow_cli/__init__.py CHANGELOG.md tests docs
    git commit -m "chore(release): vX.Y.Z"
    ```
 9. Tag and push. **Must be a signed annotated tag** (`-s`) — `.github/workflows/release.yml` rejects unsigned or lightweight tags. Requires a GPG or SSH signing key registered with your GitHub account.

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/docs/CHARACTER.md

@@ -38,12 +38,22 @@ seeding the second step with the first:
 
 1. **Face (slot 0).** gflow submits your `--face-prompt` and Flow generates the **face** image. This becomes
    the character's first reference image.
-2. **Body (slot 1).** gflow clicks the editor's slot-add ("+") button, which **auto-attaches the just-generated
-   face image as the reference seed** for the new slot. gflow then submits its **own self-contained
+2. **Body (slot 1).** gflow activates the editor's Create-Body mode, which **auto-attaches the just-generated
+   face image as the reference seed**. gflow then submits its **own self-contained
    front/side/back triptych prompt** (it wraps your `--body-prompt` body/outfit description). Because the face
    is attached as the seed, a **single credited generation** produces all three body angles — front, side, and
    back — that match the face.
 
+   The character editor is a **two-mode surface** ("Portrait" / "Create Body"). Current Flow reuses one Slate
+   editor across both modes, so gflow anchors Create Body by the locale-independent `accessibility_new` icon
+   beside the portrait-image button and requires a new generated-face reference chip to mount before using the
+   shared box. Older cohorts that mount a second prompt box remain supported through a Slate-count-rise gate. In
+   both cases gflow verifies the selected
+   body box still owns focus **before clearing or typing**. If the structural mode signal or focus check fails,
+   the body step aborts before any autosaved prompt edit; post-type isolation failures abort before the credited
+   submit. This guards the race that corrupted a stored portrait prompt live on 2026-07-25/0.43.0. Re-run
+   `gflow character create` to retry; the saga reuses the entity and completed face slot (§4).
+
 The result: two generations (face + body-triptych), the body kept on-model by the face seed. Everything else —
 naming the character, setting the voice/personality, and saving — is free metadata (REST), not generation. See
 §4 for the full saga and §6.2 for the wire payload.
@@ -269,7 +279,7 @@ is **shipped** (see the table below).
 
 | Command | Maps to |
 |---|---|
-| `gflow character create --project <id> --name <name> --face-prompt … [--body-prompt …] [--voice <Name>] [--personality …] [--model nano2\|nanopro] [--profile …] [--locale en-US] [--json]` *(SHIPPED v0.12.0 — shipped option names; characters have NO aspect-ratio control)* | createEntity → gen face (slot 0) → commit_workflow → optional gen body (slot 1) → commit_workflow → patch_entity, via the persist-before-spend saga (§4). `--body-prompt` is a **body/outfit DESCRIPTION** — gflow wraps it in a self-contained **front/side/back triptych** instruction and seeds it with the generated face (auto-attached as the slot-add reference), so one body generation yields all three angles. Generated images are **downloaded** to storage; the result reports each slot's local path. |
+| `gflow character create --project <id> --name <name> --face-prompt … [--body-prompt …] [--voice <Name>] [--personality …] [--model nano2\|nanopro] [--profile …] [--locale en-US] [--json]` *(SHIPPED v0.12.0 — shipped option names; characters have NO aspect-ratio control)* | createEntity → gen face (slot 0) → commit_workflow → optional gen body (slot 1) → commit_workflow → patch_entity, via the persist-before-spend saga (§4). `--body-prompt` is a **body/outfit DESCRIPTION** — gflow wraps it in a self-contained **front/side/back triptych** instruction and seeds it with the generated face (auto-attached as the body-mode reference), so one body generation yields all three angles. Generated images are **downloaded** to storage; the result reports each slot's local path. |
 | `gflow character list --project <id> [--json]` *(SHIPPED v0.12.0)* | projectInitialData → entities[CHARACTER] |
 | `gflow character show --project <id> (--id <entityId> \| --name <displayName>) [--json]` *(SHIPPED v0.12.0)* | projectInitialData (single); name collision → exit 11 with disambiguation hint |
 | `gflow character voices [--json]` *(SHIPPED v0.12.0)* | list the 29 preset voices (name / description / sample-url); language-agnostic discovery, mirrors `gflow models --json` |
@@ -403,7 +413,7 @@ Built by `routes.character_editor_url(locale, projectId, entityId)`. The **`/fx/
 without it Flow 404s (caught by spike T-A; the fix sourced the URL from `LABS_FX_BASE`). Navigating to this
 URL (not the new-project flow) is what makes Flow's JS set `entityContext` on the generation. Name / voice /
 personality are REST `PATCH flow/entities`. The only *new* generation selectors are the prompt/submit (already
-owned by gflow) and the slot-add.
+owned by gflow) and the body-mode activation/settle signals.
 
 | Purpose | Selector | Conf. |
 |---|---|---|
@@ -413,7 +423,7 @@ owned by gflow) and the slot-add.
 | Name field | `input[placeholder]` — localized placeholder; **do NOT rely on the text** (structural: it is the editor's lone placeholdered input) | **VERIFIED** |
 | Personality field | the panel `textarea` (localized placeholder) — **prefer REST PATCH** | **VERIFIED** |
 | Slot 0 image (face) | aria-label `"Imagem do personagem 1"` — **localized**, note only (do not load-bear on the text) | med (localized) |
-| **Slot-add (body / slot 1)** | `add_2` google-symbols ligature; the editor has **TWO** `add_2` buttons → slot-add is **`.nth(1)`** (`_CHARACTER_SLOT_ADD_SELECTOR = "button:has(i.google-symbols:text('add_2'))"`). The **first** `add_2` is the gallery "+ New project" CTA → positional disambiguation. ⚠️ confirm `.nth(1)` in the live body-gen e2e (Task 12). | **VERIFIED** (selector) / ⚠️ ordering |
+| **Body mode (slot 1)** | Current cohort: portrait-image sibling `button:has(img) + button:has(i.google-symbols:text-is('accessibility_new'))`; settle signal: a newly mounted generated-media card with an `img` and exact `cancel` icon. Legacy cohort fallback: icon-only `[role=button]` carrying exact `add_2`, followed by Slate-box count rise. No localized button text or positional index. | **VERIFIED** live 2026-07-26 |
 | Model picker (char editor) | `button[aria-haspopup='menu']:has(i.google-symbols:text-is('arrow_drop_down'))` *(normal editor uses `crop_16_9`)* | **VERIFIED** |
 | Voice picker | `voice_selection` google-symbols ligature | **VERIFIED** (ligature) |
 | Personagens nav (project) | `button:has(i.google-symbols:text-is('accessibility_new'))` (cards are `div[role=button]`; tag disambiguates) | high |
@@ -421,10 +431,10 @@ owned by gflow) and the slot-add.
 | Picker tab → Personagens | `[role=dialog] button[role=tab]:has(i.google-symbols:text-is('accessibility_new'))` | high |
 | **Picker "include in command"** | primary `button` in the dialog footer — **no ligature → structural anchor (last/primary dialog button)**; only appears *after* an option is selected | low ⚠️ |
 
-⚠️ **Documented risk (Task-12 e2e):** the slot-add `.nth(1)` ordering and the picker include button (no
-ligature, localized text only) are positional/structural anchors that must be confirmed under a live non-EN
-locale. Slot 0's `"Imagem do personagem N"` aria-label is **localized** — used as a note, never as a
-load-bearing selector.
+⚠️ **Documented risk (Task-12 e2e):** the picker include button (no ligature, localized text only) remains a
+positional/structural anchor to confirm under a live non-EN locale. Body mode no longer uses the stale
+`.nth(1)` selector; its mode and settle icons are locale-independent. Slot 0's `"Imagem do personagem N"`
+aria-label is **localized** — used as a note, never as a load-bearing selector.
 
 Shared chrome already automated by gflow (reuse as-is): `add_2` (+/Criar add-media → opens picker),
 `arrow_forward` (submit), the Slate prompt box, model dropdown, `check`/Concluir.
@@ -472,7 +482,7 @@ table → test mapping):
 
 **Remaining LIVE-e2e-only (Task 12):** the live binding/recovery/UTF-8 e2e on denon82 — real
 `parentEntityId == entityId` against Flow's wire, mid-saga crash recovery against the real DB, and the
-slot-add `.nth(1)` + picker-include structural selectors under a non-EN locale.
+body-mode icon/reference settle signals + picker-include structural selectors under a non-EN locale.
 
 ## 13.1 Known issues
 

{gflow_cli-0.43.0 → gflow_cli-0.45.0}/docs/CHARACTER_RECON.md

@@ -82,6 +82,76 @@ calls on the same `workflowId`, chaining `imageInputs` (BASE_IMAGE = prior outpu
 This is the SAME endpoint family gflow's existing image transport already drives — the new bits are
 `tool:"PINHOLE"`, `imageInputs` types, and the `parentEntityId`/workflow binding.
 
+## Entity binding: `entityContext` (captured live 2026-07-28)
+
+**The generation request must carry `entityContext`, or Flow files the image as a
+plain project image and the character stays empty.** Captured from Flow's own UI
+via a CDP-attached real Chrome (`gflow-agent-browser-spike`, `navigator.webdriver:
+false`) while driving the plain **New Character** flow.
+
+`POST /v1/projects/{projectId}/flowMedia:batchGenerateImages`
+
+```jsonc
+{
+  "clientContext": { "projectId": "…", "tool": "PINHOLE", "sessionId": "…" },
+  "mediaGenerationContext": {
+    "batchId": "…",
+    "entityContext": {
+      "entityId": "1e6c558e-87be-4aa7-8a21-ffb7efa43bbd",
+      "characterSlot": { "imageReferenceIndex": 0 }   // 0 = portrait/face, 1 = body
+    }
+  },
+  "useNewMedia": true,
+  "requests": [ { "imageModelName": "NARWHAL", "structuredPrompt": {…}, "seed": …, "imageInputs": [] } ]
+}
+```
+
+Response — bound on the first try:
+
+```jsonc
+"workflows": [ { "name": "30551aa7-…", "projectId": "…", "parentEntityId": "1e6c558e-…" } ]
+```
+
+### Which surface produces it
+
+The composer Flow renders depends on whether the character already HAS a
+portrait, not on which URL you arrived by:
+
+| Character state | Composer placeholder | Sends `entityContext`? |
+|---|---|---|
+| Empty (no portrait yet) | *"Describe your character…"* | **Yes** — this is the creation composer, on `/characters` **and** on `/character/{entityId}` |
+| Populated (portrait exists) | *"What do you want to change?"* | Edit surface — refines the existing portrait |
+
+Both entry points reach the creation composer for an empty character, and both
+bind. Verified live 2026-07-28: driving `/project/{id}/character/{entityId}` for
+a pre-created empty entity produced `entityContext` in the request and
+`parentEntityId` in the response — including for an entity gflow itself had
+created minutes earlier. Entity age is not a factor.
+
+`flow.createEntity` may be called by Flow (the **New Character** flow does it
+itself, returning `displayName: "Untitled Character"`) or by the client
+beforehand; gflow pre-creates and deep-links, which is fine. After the
+generation Flow issues `PATCH /v1/flowWorkflows/{id}` twice
+(`metadata.displayName`, then `metadata.primaryMediaId`) — the same commit gflow
+already performs. Flow never asks for a name up front: the user renames
+afterwards via the ✏️ next to the title, and "Character Info (optional)"
+(*"Describe how your character acts…"*) is a separate free-text field.
+
+**What actually broke gflow (#395)** was therefore NOT the choice of entry
+point. Two client-side defects suppressed `entityContext` on a surface that
+would otherwise have sent it:
+
+1. **Overlay dismissal pressed Escape on the composer.** `[role='dialog']` and
+   `[role='alert']` in the overlay detector matched Flow's own character
+   composer (and the media picker), so gflow dismissed the app itself.
+2. **The character route could bounce back to the project page** while the
+   entity was not yet queryable. The project page also mounts a prompt box, so
+   the readiness gate passed on the wrong surface and the prompt was typed into
+   the **project** composer.
+
+With both fixed, the deep-linked editor binds reliably. See
+[LIVE_VERIFICATION_v0.45.0 §2](LIVE_VERIFICATION_v0.45.0.md).
+
 ## Gaps
 
 1. ✅ **RESOLVED — Entity create.** `POST /fx/api/trpc/flow.createEntity` `{json:{projectId}}` →

{gflow_cli-0.43.0/website → gflow_cli-0.45.0}/docs/CONFIGURATION.md

@@ -343,9 +343,9 @@ each link in turn, so total wallclock is the sum of all link waits).
 |---|---|---|
 | `--model` | `veo-lite` | `veo-lite` / `veo-fast` / `veo-quality` / `veo-lite-lp`. `omni-flash` is rejected — it can't seed i2v links (issue #125). |
 | `--max-links N` | unset | Cap link count; exit 11 (`ConfigurationError`) if the manifest has more. A spend guardrail. |
-| `-y` / `--yes` | off | Skip the per-credit cost confirmation prompt. |
-| `--dry-run` | off | Print the plan + credit estimate and spend nothing. |
-| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-paid links are skipped (not re-billed). |
+| `-y` / `--yes` | off | Skip the pending video operation confirmation prompt. |
+| `--dry-run` | off | Print the pending video operation plan and submit nothing. |
+| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-completed links are skipped (not regenerated). |
 | `--jitter F` | `0.0` | Random `0..F` second pause **between** links (anti-bot cadence; never before link 0). |
 | `--seed-offset MS` | `0` | Extract the seed frame this many ms before EOF (fade-to-black guard). |
 | `--aspect` | `9:16` | `9:16` / `16:9`. Applied uniformly to every link (continuity requirement). |