PyPI - gflow-cli - Versions diffs - 0.38.1__tar.gz → 0.40.0__tar.gz - Mend

gflow-cli 0.38.1tar.gz → 0.40.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (615) hide show

{gflow_cli-0.38.1 → gflow_cli-0.40.0}/AGENTS.md RENAMED Viewed

@@ -116,6 +116,7 @@ The SkillOpt harness at `scripts/dev/skillopt/` measures how accurately each ski
 - **Architecture & target shape** → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - **Mandates & routing rules** → [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md)
+- **Referencing assets** (`@Name` mention vs `--reference-entity` vs `--ref`) → [docs/REFERENCE_STRATEGIES.md](docs/REFERENCE_STRATEGIES.md)
 - **Full docs index** → [docs/INDEX.md](docs/INDEX.md)
 - **Known issues** (read before touching auth / reCAPTCHA) → [KNOWN_ISSUES.md](KNOWN_ISSUES.md)
 - **Current task** → `/gflow:status` · **Create a feature plan** → `/gflow:plan <feature>` · **Full roadmap** → [PLAN.md](PLAN.md)

{gflow_cli-0.38.1 → gflow_cli-0.40.0}/CHANGELOG.md RENAMED Viewed

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.40.0] — 2026-07-19
+### Added
+- **Prompt `@`-mention resolution for asset tagging** ([#344]): `@Name` in a
+  t2i/i2i/video prompt resolves to a staged, taggable character entity
+  (`services/mentions.py`), across the `image`/`video` CLI paths, the async
+  worker, and MCP tools. Media-asset (non-character) `@`-mentions also work,
+  but on the **image path only** — video-path media mentions are Phase 3. A
+  bare character with no reference images is rejected early with a clear
+  error instead of failing deep in the UI attach. De-tagged prompts are
+  persisted to the catalog. See
+  [`docs/REFERENCE_STRATEGIES.md`](docs/REFERENCE_STRATEGIES.md) for
+  `@`-mention vs `--reference-entity` vs `--ref`, and
+  [`docs/LIVE_VERIFICATION_v0.40.0.md`](docs/LIVE_VERIFICATION_v0.40.0.md)
+  for the live e2e evidence.
+[#344]: https://github.com/ffroliva/gflow-cli/issues/344
+## [0.39.0] — 2026-07-19
+### Added
+- **Failed generations are now persisted to the local catalog** ([#341]):
+  every paid-generation path (`video t2v/i2v/r2v`, `video chain`,
+  `image t2i/i2i`, multi-prompt t2i, `gflow run`, `image batch`, `movie run`,
+  and the async worker) records a terminal `status="failed"` operation row —
+  with a stable `error_type` derived from the exception's RFC 9457
+  `problem_type` (`waf-rejection`, `content-policy`, `auth-expired`, ...) and
+  a redacted `error_detail` — before the error propagates. WAF-403 block
+  onset, duration, and recovery windows are now measurable instead of
+  reconstructed from memory.
+- New `gflow data list errors [--profile] [--limit] [--offset] [--json]`
+  subcommand: browse failed operations newest-first (Rich table on a TTY,
+  JSONL otherwise).
+- Videos whose poll completes with a Flow-reported failure
+  (`succeeded=false`, e.g. `PUBLIC_ERROR_UNSAFE_GENERATION`) are now recorded
+  as `failed` with `error_type=generation-failed` — previously they were
+  recorded as `succeeded` (all paths: CLI, chain, movie, worker).
+### Security
+- `error_detail` values are scrubbed before persistence
+  (`Bearer`/`SAPISIDHASH` tokens, auth-cookie pairs, signed URLs; 500-char
+  cap) and non-`GFlowError` messages are stored only as SHA-256 hashes.
+  Prompts on failed rows honor `GFLOW_CLI_HISTORY_PROMPTS`; note `store` mode
+  therefore also stores prompts of content-policy-rejected generations.
+- The experimental REST transports (`bearer`, `sapisidhash`,
+  `evaluate_fetch`) now redact response bodies BEFORE truncating them into
+  exception messages, closing a partial-secret leak into logs and (new) the
+  catalog DB.
+- The worker queue's `generation_queue.error_json` now applies the same
+  redaction: `GFlowError` details are scrubbed and non-`GFlowError` messages
+  are stored as SHA-256 hashes instead of raw text.
+[#341]: https://github.com/ffroliva/gflow-cli/issues/341
 ## [0.38.1] — 2026-07-17
 ### Fixed
@@ -2053,7 +2110,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.38.1...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.40.0...HEAD
+[0.40.0]: https://github.com/ffroliva/gflow-cli/compare/v0.39.0...v0.40.0
+[0.39.0]: https://github.com/ffroliva/gflow-cli/compare/v0.38.1...v0.39.0
 [0.38.1]: https://github.com/ffroliva/gflow-cli/compare/v0.38.0...v0.38.1
 [0.38.0]: https://github.com/ffroliva/gflow-cli/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/ffroliva/gflow-cli/compare/v0.36.0...v0.37.0

{gflow_cli-0.38.1 → gflow_cli-0.40.0}/CLAUDE.md RENAMED Viewed

@@ -14,6 +14,7 @@
    - Current task / where we left off → `/gflow:status`
    - Starting a new feature → `/gflow:predict` → `/gflow:scenario` → `/gflow:plan <feature>`
    - Touching auth or reCAPTCHA → `/gflow:known-issues`
+   - Referencing a saved asset (`@Name` mention vs `--ref`/`--reference-entity`) → [docs/REFERENCE_STRATEGIES.md](docs/REFERENCE_STRATEGIES.md)
    - Cutting a release → `/gflow:release`
    - Before any commit → `/gflow:check`

{gflow_cli-0.38.1 → gflow_cli-0.40.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.38.1
+Version: 0.40.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

gflow_cli-0.40.0/docs/ASSET_TAGGING_RECON.md ADDED Viewed

@@ -0,0 +1,203 @@
+# Asset tagging (`@` mentions) — research & integration design
+> **Status:** VERIFIED-with-capture · **Branch:** `claude/google-flow-asset-tagging-r3aqjb`
+> **Convention:** this is the integration recon doc for the `@`-mention surface, following the
+> `<FEATURE>_RECON.md` pattern ([INDEX § recon docs](INDEX.md)). Wire-payload sections are
+> VERIFIED as of 2026-07-18.
+> **Related:** [CHARACTER.md](CHARACTER.md) (entity model, `referenceEntities` wire), [MOVIE.md](MOVIE.md)
+> (entity-attach mechanism), [AGENT_UI_RECON.md](AGENT_UI_RECON.md) (agentic cohort), [INSTRUCTIONS.md](INSTRUCTIONS.md).
+## 1. What the feature is (product research)
+In Flow's prompt box, typing **`@`** opens a dropdown of the project's assets. Selecting one inserts a
+mention chip into the prompt text; the model then anchors on that specific asset instead of inventing a
+new one. Three asset classes are taggable:
+| Tag | Asset class | gflow equivalent today |
+|---|---|---|
+| `@CharacterName` | Saved project **Character** (entity) | `gflow character` entities — `referenceEntities` on the wire (VERIFIED, [CHARACTER § 6.6](CHARACTER.md#66-videobatchasyncgeneratevideoreferenceimages-reuse)) |
+| `@me` | Personal **Avatar / likeness** (face + voice scan, I/O 2026) | `referenceLikenesses` — **region-gated**; `GET /v1/flow/likeness:checkEligibility` returns `REGION` for our accounts ([CHARACTER § 1.1](CHARACTER.md#11-how-it-works-plain-language)) |
+| `@AssetName` | Uploaded/generated **ingredient** (image, object, style ref) | `--ref` on `video r2v` (local path only, upload-every-time — #314) and `image i2i` (path **or** in-project media UUID, zero re-upload) — `referenceImages[{mediaId, imageUsageType:IMAGE_USAGE_TYPE_ASSET}]` (VERIFIED wire shape) |
+Product-side facts from public sources (Google Flow Help, blog.google "5 tips for Flow", I/O 2026
+coverage):
+- The dropdown **searches uploaded assets by name** — it is a name→asset resolver over the project's
+  asset library, the same library the "Video Ingredients" mode and SceneBuilder draw from.
+- `@me` requires the one-time avatar scan (read numbers aloud + head turn); the likeness is stored on the
+  Google Account and referenced across Gemini/Flow. Regional gating applies (matches our
+  `likeness:checkEligibility` finding).
+- Community guidance: consistency holds best when the reference image has a **clean, uncluttered
+  background**; drift (clothing/face shifts) still occurs under heavy motion — tagging anchors identity,
+  it does not eliminate drift.
+Sources: [Google Flow Help — Create videos](https://support.google.com/flow/answer/16353334?hl=en) ·
+[blog.google — 5 tips for Flow](https://blog.google/technology/ai/flow-video-tips/) ·
+[I/O 2026 avatar coverage](https://nokiapoweruser.com/google-io-gemini-avatar-web-flow-android-update/) ·
+[vidau.ai Flow 2026 guide](https://www.vidau.ai/google-flow-ai-update-2026-complete-guide/).
+(Several guides are WAF-walled to bots; facts above were cross-checked across at least two sources.)
+## 2. What gflow already owns (VERIFIED against shipped code)
+The `@` feature is **not a new wire capability** — it is a new *UI affordance* over reference mechanisms
+gflow has already reverse-engineered and partially shipped:
+1. **Entity references ride today.** `gflow movie run` attaches a CHARACTER entity by opening the
+   resource picker, right-clicking the tile addressed as `data-tile-id="fe_id_<entityId>"`, and choosing
+   the include-in-prompt action (`PICKER_CONTEXT_INCLUDE`, locale-free icon tier — `ui_automation_video.py`).
+   The submit then carries `referenceEntities:[{entityId}]`, echoed back in
+   `workflows[].videoData.videoGenerationEntityInputs[].entityId`, asserted by `_assert_entities_attached`
+   ([MOVIE § Character consistency](MOVIE.md#character-consistency-how-the-entity-rides)).
+2. **Image references ride today — with one path-specific gap.** `gflow video r2v --ref` stages
+   `referenceImages` from **local paths only** (`click.Path(exists=True)`; upload-every-time by design —
+   #314). UUID-addressed zero-re-upload selection of existing assets is live-verified on
+   `image i2i --ref` (v0.26.0) and `video i2v` frame refs (shipped v0.32.0, live-verified v0.33.0 —
+   #287) — but an **r2v** UUID-selection
+   primitive does not exist yet, so media mentions on the *video* path are net-new transport work.
+3. **Image-path character reuse already ships.** `gflow image t2i/i2i --reference-entity` puts
+   `referenceEntities:[{entityId}]` on the image submit — wire shape captured live 2026-06-08
+   (`api/image.py`) and asserted by `_assert_image_entities_attached`. (CHARACTER.md §14's
+   "image-path `referenceEntities` uncaptured" bullet was stale; corrected in this PR.) What's missing
+   is only the name-based `@` syntax over it.
+4. **Name→asset resolution exists.** `flow.projectInitialData` returns entities with `displayName`
+   ([CHARACTER § 6.5](CHARACTER.md#65-flowprojectinitialdata-listshow)); the local catalog records
+   generated-image `display_name` (v0.26.0). This is exactly the lookup the `@` dropdown performs.
+5. **The prompt box is a Slate editor.** `_send_prompt` targets
+   `div[role="textbox"][data-slate-editor="true"]` and uses `keyboard.insert_text` (one `beforeinput`
+   event, Slate-native). A mention chip is a **non-text Slate node** — `insert_text` alone can never
+   create one.
+6. **Diagnostics are pre-staged.** The image-submit capture already probes for `referenceEntit` in POST
+   bodies (`mentions_reference_entities`, `ui_automation.py`) — built for the #170 submit backstop and
+   directly reusable here.
+**Gaps the `@` feature would close:**
+- `gflow video --character` (Phase 3 backlog, [CHARACTER § 14](CHARACTER.md#14-backlog--not-yet-implemented)) — single-command character reuse outside the movie pipeline.
+- Name-based reference syntax everywhere — the image path already has id-based `--reference-entity`;
+  nothing accepts an asset *name*.
+- Inline, per-prompt asset naming (`"@Zoro hands @Mika the sword"`) — today references are flag-level
+  (whole-generation), not positional in the prompt text.
+- Media mentions on the **video** path — requires the missing r2v UUID-selection primitive (item 2).
+## 3. Wire serialization verdict (VERIFIED — H1)
+Spike results confirmed:
+- **H1 — flags-equivalent (VERIFIED):** the chip's display text lands as plain text inside
+  `structuredPrompt.parts[].text`, and the referenced asset is added to `referenceEntities` /
+  `referenceImages` exactly as the picker path does. The chip is UI sugar; position in the prompt is not
+  semantically encoded on the wire. Thus, gflow can synthesize identical payloads with the
+  **already-live-verified attach primitives** (Option B) and does not need to drive the dropdown.
+- **H2 — positional parts (REJECTED):** `structuredPrompt.parts` does not interleave mention parts; it is plain text.
+- `@me` maps to `referenceLikenesses` — **held** as region-ineligible.
+Agent-mode nuance: in the **agentic cohort** ([AGENT_UI_RECON.md](AGENT_UI_RECON.md)) the prompt feeds a
+reasoning agent, which may resolve `@Name` text itself even without a chip. The spike should test both
+cohorts; classic is the contract-bearing path.
+## 4. Integration options
+> Option letters below are local to this doc — they do **not** correspond to CHARACTER.md § 11's
+> "Option A/B" (which named direct-REST vs UI-driven *generation* transports).
+| | Option A — drive the dropdown | Option B — CLI-side mention parsing → existing attach primitives | Option C — direct REST |
+|---|---|---|---|
+| Mechanism | Type prompt up to `@`, pause, let Flow's dropdown open, select entry (structural selectors), continue typing | Parse `@Name` tokens CLI-side; resolve names via `projectInitialData` + media catalog; attach via shipped picker/UUID primitives; submit prompt with names as plain text | Build `referenceEntities`/mention parts ourselves and POST |
+| Fidelity | Exact — Flow's JS builds the chip | Equivalent **iff H1**; loses positional semantics if H2 | n/a |
+| New selector surface | High (dropdown container, search behavior, per-type entries, both cohorts, all locales) | **Zero** — reuses `fe_id_<entityId>` tiles + `PICKER_CONTEXT_INCLUDE` + UUID picker, all live-verified | n/a |
+| Risk | New drift surface; dropdown is keystroke-timing sensitive (Slate `insert_text` won't trigger it — needs real per-char typing around `@`) | Name-resolution ambiguity (duplicate display names) — solvable with exit-11 disambiguation, same as `character show --name` | **DEAD** — generation POSTs are reCAPTCHA-walled (403, spike-proven) |
+**Recommendation: Option B first, gated on a capture spike that decides H1 vs H2.** If H1 holds
+(likely — the picker path already produces accepted `referenceEntities` submits), gflow gets `@` mentions
+with no new UI automation at all: the feature becomes a *prompt-syntax resolver* in front of
+live-verified machinery. Option A is the fallback only if H2 is proven **and** positional semantics
+demonstrably change output.
+## 5. Proposed CLI surface (Phase 1, post-spike)
+Inline mentions in the prompt on generation commands, mirroring Flow's own syntax:
+```bash
+gflow video t2v "@CaptainZoro walking through a rain-soaked neon city, tracking shot" --project <id>
+gflow video r2v "@Zoro hands @Mika the sword" --project <id>          # multi-ref (cap-checked)
+gflow image i2i "@logo on a black tee, studio light" --project <id>
+gflow movie run film.toml                                              # scene prompts may carry @mentions
+```
+Rules:
+- **Grammar:** `@` + longest match against project asset names (chip names may contain spaces —
+  resolver tries greedy longest-match, then falls back to single-token). `@@` escapes a literal `@`;
+  email-like tokens (`a@b.com`) are never treated as mentions (require `@` at token start).
+- **Resolution order:** CHARACTER entities (`projectInitialData.displayName`, case-insensitive) →
+  project media assets by `display_name` (catalog first, live listing fallback). Unknown mention →
+  exit 11 `ConfigurationError` listing available names; ambiguous → exit 11 with disambiguation
+  (same contract as `character show --name`).
+- **`@me`:** check `likeness:checkEligibility` and fail with a clear "avatar likeness is region-gated /
+  not supported yet" hint (exit 11). Never silently drop.
+- **Semantics:** each resolved mention stages the corresponding reference (entity-attach or UUID
+  `--ref`), deduped against explicitly passed `--ref` / `--reference-entity` flags; model reference caps
+  (`reference_cap_for`) enforced pre-submit. Prompt text keeps the name (minus `@`) so the model sees the
+  sentence Flow's chip would render.
+- **Provenance:** record resolved mentions in `metadata_json` as `{name, kind, id}` (ids always;
+  names hashed under `GFLOW_CLI_HISTORY_PROMPTS=redacted` — see the spec § 6); structlog event per
+  resolution (`mention_resolved`, `mention_unresolved`).
+- **MCP & CLI symmetry:** mention parsing lives in a shared service (`services/`), so the MCP generation
+  tools get it for free; parity enforced by `tests/mcp/test_cli_parity.py` (AGENTS.md § MCP & CLI Schema
+  Symmetry).
+- Optional explicit form for scripts that don't want magic prompt parsing: `--tag NAME` (repeatable),
+  semantically identical to an `@NAME` mention — **Phase 3** (see § 8); not part of the first delivery.
+## 6. Spike plan (pre-implementation, ~1–2 Veo/Imagen credits)
+`scripts/dev/spike_mention_capture.py`, run live on denon82 (same pattern as
+`spike_movie_attach_payload.py`):
+1. **T-1 (0 credits):** in a crowded project, focus the prompt box, real-keystroke `@` (per-char
+   `keyboard.type`, not `insert_text`), dump the dropdown DOM (container role, tile addressing — is it
+   `fe_id_<id>` again?, search filtering, asset-type sections). *(Agentic-cohort repeat: optional —
+   Option-A prep only; run it only if H2 is proven.)*
+2. **T-2 (0 credits, optional):** select a character mention, then dump the Slate document (chip node
+   shape) — `document.querySelector('[data-slate-editor]')` innerHTML + Slate data attrs. *Only needed
+   if the T-3/T-4 POST captures are ambiguous, or if Option A is ever pursued.*
+3. **T-3 (1 credit, image):** submit with one character mention; capture the POST body
+   (`mentions_reference_entities` probe + full `requests[0]` keys) and diff it against a
+   `--reference-entity` submit body (already-captured shape, `api/image.py`). **Decides H1 vs H2** for
+   the image path: an identical body = H1.
+4. **T-4 (1 credit, video, optional if T-3 is conclusive):** same for `t2v`; diff against the known
+   picker-attach body from the movie captures.
+5. **T-5 (0 credits):** mention an *uploaded ingredient* (not a character); capture whether it lands in
+   `referenceImages` and with which `imageUsageType`.
+Exit criteria: **one of three verdicts recorded here** — H1, H2, or **INCONCLUSIVE** (no chip could be
+produced under automation, or captures ambiguous, or mixed per-path results — record per-path verdicts
+separately in that case). INCONCLUSIVE or mixed is treated like H2 for gating: STOP and re-run
+`/gflow:predict` with the evidence before implementation. Dropdown selector table (locale-free tiers)
+appended if — and only if — Option A is ever needed.
+## 7. Risks & open questions
+- **H2 positional parts** would force dropdown automation (Option A) — new selector surface on a
+  keystroke-sensitive widget, both cohorts, plus locale variance. Mitigated by spike-first gating.
+- **Name collisions / renames:** display names are not unique; Flow's dropdown disambiguates visually,
+  a CLI cannot — exit-11 disambiguation (by id) is mandatory, and manifests should prefer ids.
+- **Agentic cohort drift:** the agentic composer may render mentions differently or resolve them
+  server-side; the #174 include-lands-but-never-submits A/B applies to any staged-reference path —
+  reuse `ENTITY_ATTACH_DRIFT_HINT` backstops.
+- **`@me`:** blocked on likeness eligibility (REGION) — ship detection + honest error only.
+- **Prompt-expansion interaction:** `--tool creative-director` rewrites prompts — mentions must be
+  extracted **before** expansion and re-validated after (the expander must not invent or destroy tags);
+  simplest rule: resolve mentions first, pass the de-tagged text to the tool.
+- **Movie style blocks / instructions cards:** `[style]` composition appends text — ensure composition
+  never corrupts `@` tokens (escaping tests).
+## 8. Phasing
+| Phase | Deliverable | Gate |
+|---|---|---|
+| 0 | This recon doc | — |
+| 1 | Capture spike (§6) → H1/H2 verdict recorded here | `/gflow:predict` on the chosen option |
+| 2 | Mention resolver service + inline mentions — characters on `video t2v/r2v` (entity attach) and characters + media on `image t2i/i2i` (`--reference-entity` / UUID `--ref` paths) — + MCP parity + docs/tests | `/gflow:plan asset-tagging`, TDD, live e2e per verification-ledger norms |
+| 3 | `movie` manifest mentions; `--tag` explicit form; **video-path media mentions** (requires the new r2v UUID-selection primitive); close `video --character` backlog via the same resolver | live e2e |
+| 4 (held) | `@me` likeness — revisit when `checkEligibility` stops returning `REGION` | — |

{gflow_cli-0.38.1/website → gflow_cli-0.40.0}/docs/CHARACTER.md RENAMED Viewed

@@ -8,9 +8,11 @@
 > built **greenfield off `develop`, NOT stacked on #123** (that branch is CONFLICTING and likeness-specific;
 > see [Design decisions](#11-design-decisions-post-predict)).
-> **Shipped scope:** `gflow character create` + `list` + `show` + `voices` + `rm`. The reuse path
-> `gflow video --character` (Phase 3) and `gflow image --character` are **not yet
-> implemented** — see [Backlog](#14-backlog--not-yet-implemented).
+> **Shipped scope:** `gflow character create` + `list` + `show` + `voices` + `rm`. Name-based reuse via
+> `@Name` prompt mentions is **shipped** (v0.40.0, [#344](https://github.com/ffroliva/gflow-cli/issues/344))
+> for both `image` and `video` paths — see [REFERENCE_STRATEGIES](REFERENCE_STRATEGIES.md). An explicit
+> `--character <id>` **flag** on `gflow video` (a separate, repeatable-ref delivery mechanism) remains
+> **not yet implemented** — see [Backlog](#14-backlog--not-yet-implemented).
 > **Status (2026-06-02, LIVE-VERIFIED):** the create saga + character-editor UI generation are **shipped**
 > and verified end-to-end on denon82 (face + front/side/back triptych body, both reference slots bound,
@@ -259,9 +261,11 @@ both normalize to the canonical `Charon`) and sets `audioReferences[].presetVoic
 The `create` / `list` / `show` / `voices` commands below are **shipped and
 live-verified in v0.12.0** (the user-facing reference lives in
-[USAGE § `gflow character`](USAGE.md#gflow-character)). The `gflow video --character`
-reuse path and `gflow image --character` remain **backlog** (rows marked *not
-yet implemented*). `gflow character rm` is **shipped** (see the table below).
+[USAGE § `gflow character`](USAGE.md#gflow-character)). Name-based reuse via
+`@Name` prompt mentions is **shipped** (v0.40.0, #344) on both the image and
+video paths. An explicit `--character <id>` **flag** on `gflow video`
+remains **backlog** (row marked *not yet implemented*). `gflow character rm`
+is **shipped** (see the table below).
 | Command | Maps to |
 |---|---|
@@ -269,9 +273,10 @@ yet implemented*). `gflow character rm` is **shipped** (see the table below).
 | `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` |
-| `gflow video … --character <id>` *(repeatable → multi-ref)* | **not yet implemented** (Phase 3) — `referenceEntities` on `video:batchAsyncGenerateVideoReferenceImages` |
+| `gflow video … --character <id>` *(repeatable → multi-ref, explicit flag)* | **not yet implemented** (Phase 3) — `referenceEntities` on `video:batchAsyncGenerateVideoReferenceImages` |
 | `gflow character rm` (`--id`/`--name`) | **Shipped v0.13.0 (#150)** — `POST flow:batchDeleteAssets` (Bearer; FREE — no reCAPTCHA/credit) |
-| `gflow image … --character <id>` | **not yet implemented** — image-path `referenceEntities` uncaptured |
+| `gflow image … --character <id>` *(explicit flag)* | id-based reuse **shipped** as `gflow image t2i/i2i --reference-entity <id>` (wire captured 2026-06-08, `api/image.py`) |
+| `@Name` in a t2i/i2i/video prompt | name-based mention resolution **shipped v0.40.0 (#344)** — resolves to the staged character entity, works on both image and video paths; see [REFERENCE_STRATEGIES](REFERENCE_STRATEGIES.md) |
 All commands take **`--project <id>` (required)** — every endpoint (`createEntity`, `projectInitialData`,
 reuse) is project-scoped; mirrors `gflow scene` / `gflow data` ergonomics. Use `--id`/`--name` flags, never a
@@ -305,7 +310,8 @@ never hard-code wire names in user-facing help — see [[cli-model-aliases-verif
 ## 10. Open items
 See [§14 Backlog — not yet implemented](#14-backlog--not-yet-implemented) for the consolidated list. In
-short: `gflow video --character` reuse (Phase 3), `gflow image --character`, live voice
+short: an explicit `--character <id>` flag on `gflow video` reuse (Phase 3; `@Name` prompt mentions
+already ship this on both image and video, see #344), live voice
 listing + `presetVoiceId` wire-case confirmation, custom-voice creation, `nanopro` picker live confirmation,
 and extra body angles. The optional creation-agent (`flowCreationAgent/sessions`,
 `flow.generateCharacterPrompt` archetypes) is not required for the scripted path; consider an `--archetype`
@@ -490,14 +496,19 @@ The following are explicitly **out of the shipped scope** and tracked for future
 - **Model-picker live confirmation.** `--model nanopro` is wired **best-effort / non-fatal** (a picker miss
   warns and continues rather than failing); an explicit live run is needed to confirm `nanopro` is actually
   selected in the character editor.
-- **`gflow video --character` (Phase 3).** Reuse a character in a video generation via `referenceEntities`
-  on `video:batchAsyncGenerateVideoReferenceImages` (repeatable → multi-reference). Wire protocol is captured
-  (§5, §6.6) but the command is **not yet built**.
+- **`gflow video --character <id>` (explicit flag, Phase 3).** Reuse a character in a video generation via
+  an explicit repeatable `--character <id>` flag, as a `referenceEntities` alternative to `@Name` prompt
+  mentions (which already work on the video path, shipped v0.40.0/#344). Wire protocol is captured (§5,
+  §6.6) but the flag-based command is **not yet built**.
 - **Extra body angles beyond the built-in triptych.** The shipped body slot generates a single front/side/back
   triptych. Generating additional angles/poses (e.g. re-feeding the front view as a reference seed for a new
   slot) is a future enhancement.
-- **`gflow image --character`.** The **image-path** reuse (`referenceEntities` on the image endpoint) is
-  uncaptured — deferred until its wire shape is reverse-engineered. (`gflow character rm` is now shipped, #150.)
+- ~~**`gflow image --character` (name-based).**~~ **Shipped v0.40.0 (#344)** as `@Name` prompt mentions
+  (`services/mentions.py`), on both image and video paths for character references. The image-path wire
+  shape (`gflow image t2i/i2i --reference-entity <id>`) shipped earlier (live capture 2026-06-08,
+  `api/image.py`; asserted by `_assert_image_entities_attached`). See
+  [REFERENCE_STRATEGIES](REFERENCE_STRATEGIES.md) for the decision guide across all three mechanisms.
+  (`gflow character rm` is now shipped, #150.)
 - **Set the Flow editor title field** so the editor isn't "Untitled Character" (see [§13.1 Known issues](#131-known-issues)).
   Investigate either the UI title box (with a Ctrl+A merge-bug workaround) or finding the dedicated title
   field/endpoint that the editor widget reads from, distinct from `entityInfo.displayName`.

{gflow_cli-0.38.1 → gflow_cli-0.40.0}/docs/DATA_LAYER.md RENAMED Viewed

@@ -133,6 +133,39 @@ For T2V the sequence is split: `record_started_video(...)` fires the moment the
 For batches, each row is recorded individually in a per-row `try/except DataStoreError`, so one row's persistence failure does not stop the rest of the batch.
+### Failure recording (#341, v0.39.0+)
+Failed generations are first-class catalog citizens: every paid-generation
+orchestrator records a terminal `status="failed"` operation row before
+re-raising the error. The funnel covers `video t2v/i2v/r2v`, `video chain`
+(per-link, via the `on_link_failed` hook), `image t2i/i2i`, multi-prompt
+t2i / `gflow run` / `image batch` manifest rows, `movie run` scenes, and the
+async worker (which mirrors its `generation_queue.error_json` failure into
+`operations` — the operations table owns terminal truth).
+- `error_type` is the last segment of the exception's RFC 9457 `problem_type`
+  URI (`waf-rejection`, `content-policy`, `auth-expired`,
+  `transport-timeout`, ...) — the taxonomy is declared per `GFlowError`
+  subclass, never hand-mapped. Non-`GFlowError` exceptions store the class
+  name, with `error_detail` reduced to a SHA-256 hash of the message (never
+  the text — it may carry tokens).
+- Video failures UPDATE every `on_started` STARTED row to `failed` (a
+  `count>1` request fires the callback per output — no sibling row is
+  stranded); failures before `on_started`, and all image failures, INSERT a
+  fresh row with full request metadata.
+- A poll that COMPLETES with a Flow-reported failure (`succeeded=false`) is
+  recorded as `failed` with `error_type=generation-failed` and the
+  `failure_reasons` as detail — not as a success.
+- The write itself is best-effort: `record_failed_operation_safe` wraps it in
+  a broad warn-only guard (`failure_record_skipped` structlog event) so a
+  data-layer fault can never mask the generation error or change the exit code.
+- The character-create saga deliberately keeps its STARTED rows for resume —
+  it is excluded from the failure funnel by design.
+- `failed` rows accumulate without an automatic cap in this release: `gflow
+  data prune` targets stale in-flight/completed entries, not failed-operation
+  history. Bounded retention and a dedicated export are tracked in
+  [#345](https://github.com/ffroliva/gflow-cli/issues/345).
 ---
 ## Persistence-failure handling
@@ -179,6 +212,20 @@ The hash is always stored so you can correlate without the plaintext.
 This means the recorder OWNS redaction — call sites cannot leak signed URLs into the DB even by accident, because `OperationRecorder` always pipes metadata through `redact_metadata` before writing.
+### `error_detail` redaction (#341)
+Failure rows persist the exception's Problem-Details `detail` string through
+[`redact_error_detail`](../src/gflow_cli/data/redaction.py): free-text
+`Bearer …` / `SAPISIDHASH …` tokens and auth-cookie pairs become
+`<redacted:secret>`, URLs carrying signed-query markers become
+`<redacted:url>`, and the result is truncated to 500 chars post-redaction as
+defense-in-depth. The experimental REST transports also redact response bodies
+BEFORE truncating them into exception messages, so a clipped secret can't
+reach the DB. Non-`GFlowError` details are stored only as SHA-256 hashes.
+Prompts on FAILED rows honor `GFLOW_CLI_HISTORY_PROMPTS` exactly like success
+rows — note that in `store` mode this includes prompts of content-policy
+REJECTED generations (the same opt-in that stores successful prompts).
 ### What the DB still contains
 Even with `redacted` mode and metadata stripping, the DB stores: profile names, Flow project/media/workflow/operation IDs, local file paths or cloud URIs, asset dimensions/seeds/timestamps, model and aspect choices, and prompt hashes. If your threat model requires hiding even profile-level activity, exclude `<GFLOW_CLI_HOME>/gflow.db` from backups or set `GFLOW_CLI_DB_PATH` to a per-task ephemeral location.
@@ -189,7 +236,7 @@ See [`SECURITY.md`](SECURITY.md) for the broader threat model.
 ## Querying the data layer
-### `gflow data list {projects,images,videos,profiles}` — browse the catalog (v0.9.0+)
+### `gflow data list {projects,images,videos,profiles,errors}` — browse the catalog (v0.9.0+)
 ```bash
 # Newest 20 projects across all profiles
@@ -206,9 +253,14 @@ gflow data list videos --json | jq '.media_id'
 # Profiles with at least one recorded generation
 gflow data list profiles
+# Failed generations, newest first (#341): when, which command/mode/model,
+# stable error_type (waf-rejection, content-policy, ...) + redacted detail.
+# The dataset for WAF-cadence and reliability analysis.
+gflow data list errors --profile denon82 --json | jq '{started_at, error_type}'
 ```
-Flags shared by all four subcommands:
+Flags shared by all five subcommands:
 | Flag | Default | Notes |
 |---|---|---|
@@ -392,6 +444,13 @@ All three are subclasses of `GFlowError` and re-exported through `gflow_cli.exce
 See [`errors.py::EXIT_CODE_MAP`](../src/gflow_cli/errors.py) for the complete exit-code mapping.
+Distinct from the above (which are errors OF the data layer), the
+`operations.error_type` column stores the taxonomy of RECORDED generation
+failures — the last segment of each exception's `problem_type` URI. Common
+values: `waf-rejection` (HTTP 403 / WAF), `content-policy`, `auth-expired`,
+`transport-timeout`, `wire-format`, `rate-limit`, `ui-mode-unavailable`
+(cohort pin), `media-attribution`. Query them with `gflow data list errors`.
 ---
 ## Extending the data layer

{gflow_cli-0.38.1 → gflow_cli-0.40.0}/docs/INDEX.md RENAMED Viewed

@@ -36,6 +36,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/SECURITY.md](SECURITY.md)** | What secrets are stored where, threat model, hardening | Audit, code review, multi-user machines |
 | **[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/REFERENCE_STRATEGIES.md](REFERENCE_STRATEGIES.md)** | How to reference an asset: `@Name` mention vs `--reference-entity` vs `--ref` — the two-axis model (identity vs image), same-wire+dedupe rule, per-path support matrix, image-less-entity prerequisite, agent rule | Deciding how to tag a saved character/asset in a prompt, or wiring `@`-mentions into a generation |
 | **[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/TOOLS.md](TOOLS.md)** | Tools framework: the `gflow tools list/show/run` group, the `--tool/-t` option on generation commands, the TOML tool schema, how a tool is defined, "My Tools" user-authored tools, MCP exposure + §61 parity | Working on `gflow_cli.tools`, adding a built-in or user tool, or wiring `--tool` into a command |
 | **[docs/INSTRUCTIONS.md](INSTRUCTIONS.md)** | Agent Instructions: project-brief cards for Flow's Agent Mode — the mechanism (enabled cards steer generation via the reasoning path), ephemeral `-i` vs persistent cards, the `gflow instructions` CRUD surface with the single generic `--ref` (image **or** character), and the 3-layer pipeline | Working on `-i`/agent instructions, the `gflow instructions` group, or understanding how the project brief anchors generations |
@@ -43,12 +44,15 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)** | The `creative-director` tool: 5-component formula, 15 domain styles, banned-keyword policy, Gemini endpoint + I/O, never-fatal contract, `expanded_prompt` + `metadata_json.tool` provenance/redaction, config | Using or debugging `--tool creative-director`, editing the tool TOML, or auditing recorded prompt provenance |
 | **[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) |
 | **[docs/AGENT_UI_RECON.md](AGENT_UI_RECON.md)** | Agentic Flow UI cohort: classic-vs-agentic DOM signature, server-side + volatile (flapping) A/B gating (no client-readable flag), why `_exit_agent_mode` fails, runtime-DOM-detection recommendation | Touching `_exit_agent_mode` / composer mode-switch, diagnosing exit 23 selector drift, or understanding Flow's agentic-UI A/B (#183/#174) |
+| **[docs/ASSET_TAGGING_RECON.md](ASSET_TAGGING_RECON.md)** | `@`-mention asset tagging research & integration design: what Flow's `@CharacterName`/`@me`/`@ingredient` tags are, how they map onto the already-verified `referenceEntities`/`referenceImages` wire, the H1-vs-H2 serialization hypothesis, the CLI-side mention-resolver proposal, and the pre-implementation capture spike plan | Working on inline `@` mentions in prompts, `video --character` reuse, or planning the mention-capture spike |
 | **[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 |
 | [docs/superpowers/specs/2026-07-04-pr-triage-autopilot-design.md](superpowers/specs/2026-07-04-pr-triage-autopilot-design.md) | PR-triage autopilot design spec: Stage 0/1 gate, Docker sandboxing, Telegram and audit ledger | Reviewing or auditing the automated PR-triage setup |
 | [docs/superpowers/plans/2026-07-08-pr-triage-autopilot/PLAN.md](superpowers/plans/2026-07-08-pr-triage-autopilot/PLAN.md) | Implementation plan for the PR-Triage Autopilot | Tracking task-by-task execution |
+| [docs/superpowers/specs/2026-07-18-asset-tagging-design.md](superpowers/specs/2026-07-18-asset-tagging-design.md) | Asset-tagging (`@`-mention) design spec: mention grammar, resolution contract, Option-B architecture, error taxonomy, spike gate | Reviewing or implementing the `@`-mention feature |
+| [docs/superpowers/plans/2026-07-18-asset-tagging/PLAN.md](superpowers/plans/2026-07-18-asset-tagging/PLAN.md) | Task-by-task implementation plan for asset tagging (spike gate → resolver → CLI/MCP → live e2e) | Tracking task-by-task execution of the `@`-mention feature |
 ## Agent commands
@@ -84,6 +88,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"How do I chain clips into one continuous video (initial-frame I2V)?"** → [USAGE § `gflow video chain`](USAGE.md#gflow-video-chain)
 **"How do I stitch existing clips into one extended .mp4 (credit-free, no ffmpeg)?"** → [USAGE § `gflow scene`](USAGE.md#gflow-scene)
 **"How do I create a reusable character (face + body) I can reuse across generations?"** → [USAGE § `gflow character`](USAGE.md#gflow-character) · design: [CHARACTER](CHARACTER.md)
+**"Should I use an `@mention`, `--reference-entity`, or `--ref` to tag an asset?"** → [REFERENCE_STRATEGIES](REFERENCE_STRATEGIES.md) — saved named identity → `@Name`/`--reference-entity`; one-off image → `--ref`
 **"How do I turn a terse prompt into a vivid one before generating?"** → `--tool creative-director:style=cinema` on any generation command — see [PROMPT_EXPANSION](PROMPT_EXPANSION.md) · framework: [TOOLS](TOOLS.md)
 **"What tools are available and what styles do they support?"** → run `gflow tools list` / `gflow tools show creative-director` — see [TOOLS](TOOLS.md)
 **"How do I make Flow's agent follow a style/reference across a project's generations?"** → agent instruction cards — ephemeral `-i "text"` (shipped) or the persistent `gflow instructions` group with a generic `--ref` (image or character), see [INSTRUCTIONS](INSTRUCTIONS.md)
@@ -125,8 +130,8 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
-**"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships. Pre-capture research recons: [ASSET_TAGGING_RECON](ASSET_TAGGING_RECON.md) (`@`-mention asset tagging — shipped in v0.40.0, see [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md)).
 **"What was live-verified for 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.38.1__tar.gz → 0.40.0__tar.gz

gflow-cli 0.38.1tar.gz → 0.40.0tar.gz