gflow-cli 0.58.0__tar.gz → 0.59.0__tar.gz

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/.env.template

@@ -143,6 +143,13 @@
 # editable/source installs. Set to 0 to disable.
 # GFLOW_CLI_UPDATE_CHECK=1
 
+# Whether generation prompts (and the prompt-derived display names used as the
+# picker search key) are stored in the local catalog — store | redacted.
+# Under 'redacted', `gflow doctor` reports missing display names as info
+# (backfill is deliberately suppressed) instead of warn, and name backfill via
+# `gflow data sync --names` requires switching back to 'store' first.
+# GFLOW_CLI_HISTORY_PROMPTS=store
+
 # MCP no-spend mode (#496): when set to 1, the MCP server (gflow mcp run AND
 # gflow serve) never registers the credit-spending generate tools — agents
 # cannot see them in tools/list. Equivalent to the --no-spend flag.

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/AGENTS.md

@@ -58,7 +58,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–31, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–31, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping. Exit 33 is reserved outside that map: `gflow doctor` findings-present — a successful diagnosis, not an error class.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **YAGNI / least-code**: prefer the smallest change that works. No speculative abstractions (interface/factory with one implementation), no config or flags nobody sets, no dead constants/helpers, no reinventing the stdlib. Review carries this as its own lens — the **D14 over-engineering** dimension of [`pr-council-review`](skills/pr-council-review/SKILL.md) (baseline, always runs). Its rubric is portable; the `ponytail` plugin (see CONTRIBUTING) is an optional accelerant, not a dependency.
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.59.0] — 2026-08-16
+
+### Added
+
+- **Refresh-on-miss: stale catalog names self-heal during generation
+  ([#546](https://github.com/ffroliva/gflow-cli/issues/546)).** When a UUID
+  reference's picker name-search misses (e.g. the asset was renamed in the
+  Flow UI after being cataloged), the transport now consults the credit-free
+  `flow.projectInitialData` listing once (~0.5 s) for the *current* name,
+  retries the search exactly once, and attaches the existing tile — instead
+  of silently downgrading to a duplicate upload. The fresh name is written
+  back with `sync.source = "refresh"` provenance (`store` history mode only;
+  `redacted` heals the run without touching disk). Applies to `image i2i
+  --ref <uuid>` and `video i2v` frame refs; any resolver failure is logged
+  and the pre-existing fallback chain proceeds unchanged. Completes the
+  [#543](https://github.com/ffroliva/gflow-cli/issues/543) freshness model —
+  see [MEDIA_LIBRARY § freshness](docs/MEDIA_LIBRARY.md).
+
+- **`gflow doctor` — read-only pre-flight diagnostics
+  ([#542](https://github.com/ffroliva/gflow-cli/issues/542)).** Ten checks
+  across the catalog (missing display names / local files / sha256), the
+  database (migration drift, WAL state + `PRAGMA quick_check`), stuck
+  operations and queue tasks (24h recency threshold), and the environment
+  (deprecated env vars, missing Playwright Chromium, auth profiles without
+  cookies). Brew-doctor philosophy: diagnoses, never heals — nothing is
+  migrated, repaired, or written, and all DB access is strictly read-only.
+  Exit `0` when clean, `33` when any warn/fail finding is present (a
+  successful diagnosis, not an error class); internal errors keep their typed
+  codes (e.g. `16` for `DataStoreError`). `--json` emits an experimental
+  machine-readable envelope (`overall_status` + per-check `checks[]` entries).
+  Output is redaction-safe: rows are identified by UUID only, paths are
+  sanitized, and under `GFLOW_CLI_HISTORY_PROMPTS=redacted` the display-name
+  check reports info instead of warn. See
+  [USAGE § `gflow doctor`](docs/USAGE.md#gflow-doctor).
+
+- **`gflow data sync --names` — reconcile catalog display names from Flow's
+  listing endpoint ([#543](https://github.com/ffroliva/gflow-cli/issues/543)).**
+  Sweeps nameless catalog rows project-by-project via the credit-free
+  `flow.projectInitialData` listing (~0.5s/project, session-cookie auth, no
+  generation surface) and writes back the display names the picker searches
+  by — restoring the [#529](https://github.com/ffroliva/gflow-cli/issues/529)
+  picker contract (search by name, verify by UUID) for rows recorded before
+  their caption existed. Rows whose media no longer exists remotely are
+  ghost-marked `sync.status = "missing_remote"` (tombstones, never deletions)
+  only when the listing is provably complete. Write-by-default with
+  `--dry-run` preview; scoped via `--project` / `--limit` / `--since` /
+  `--max-projects`; idempotent re-runs. Refuses under
+  `GFLOW_CLI_HISTORY_PROMPTS=redacted` (exit `11`); exit `34`
+  (`SyncPartialError`, retryable) when some projects fail mid-sweep. This is
+  the remediation `gflow doctor`'s missing-display-name check points at. See
+  [USAGE § `gflow data sync`](docs/USAGE.md#gflow-data-sync).
+
 ## [0.58.0] — 2026-08-16
 
 ### Fixed
@@ -3021,7 +3073,8 @@ 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.58.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.59.0...HEAD
+[0.59.0]: https://github.com/ffroliva/gflow-cli/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/ffroliva/gflow-cli/compare/v0.57.1...v0.58.0
 [0.57.1]: https://github.com/ffroliva/gflow-cli/compare/v0.57.0...v0.57.1
 [0.57.0]: https://github.com/ffroliva/gflow-cli/compare/v0.56.0...v0.57.0

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/KNOWN_ISSUES.md

@@ -142,7 +142,7 @@ full-page media-library UI (#174) can fail earlier at `mode_switch_trigger`.
 
 ### Fresh generations may record without a `display_name` (async Flow caption)
 
-- **Status:** Open — tracked in [#543](https://github.com/ffroliva/gflow-cli/issues/543) (backfill command)
+- **Status:** Mitigated — remedies shipped via [#543](https://github.com/ffroliva/gflow-cli/issues/543) and [#542](https://github.com/ffroliva/gflow-cli/issues/542)
 - **Affected:** UUID `--ref` / frame references to *just-generated* assets (v0.58.0+)
 
 Flow computes an asset's caption (`displayName`) asynchronously server-side, so
@@ -151,9 +151,11 @@ stores no name (observed live 2026-08-16 during the r2v e2e). Such rows skip
 the picker-selection path and use the integrity-verified local-file upload
 fallback instead — correct but a duplicate upload. Also by design, rows
 recorded before v0.58.0 and all rows under
-`GFLOW_CLI_HISTORY_PROMPTS=redacted` have no stored name. #543 proposes a
-credit-free, privacy-gated `gflow data backfill-names` command; #542's
-`gflow doctor` will surface the affected-row count.
+`GFLOW_CLI_HISTORY_PROMPTS=redacted` have no stored name. **Remedies:**
+`gflow data sync --names` (#543) backfills names credit-free from the Flow
+listing endpoint (privacy-gated to `store` history mode), and `gflow doctor`
+(#542) surfaces the affected-row count. Freshly generated rows whose caption
+has not landed yet stay nameless until the next sync sweep.
 
 ### Video duration tab probe misses on the current Frames-submode DOM
 

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.58.0
+Version: 0.59.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.58.0 → gflow_cli-0.59.0}/docs/DATA_LAYER.md

@@ -69,6 +69,30 @@ same treatment `character create` already gave them. Keep that in mind before
 adding a key here: anything prompt-derived must be hashed by its own builder
 (as `tool` does) rather than relying on column-level redaction.
 
+### Asset `metadata_json.sync.*` provenance (#543)
+
+`assets.metadata_json` carries a `sync` object recording what
+`gflow data sync --names` did to the row and when — so a restored name is
+distinguishable from one recorded at generation time, and a ghost mark carries
+its own audit trail:
+
+| Key | Shape | Writer |
+|---|---|---|
+| `sync.named_at` | UTC ISO timestamp | `DataRepository.set_asset_display_name` — set (with `$.display_name`) when a sync sweep writes or overwrites the name; skipped when the stored name is already identical, so re-runs never churn the timestamp |
+| `sync.source` | `"sync"` \| `"refresh"` | Same writer, same statement — provenance for the name value: `"sync"` from a bulk `gflow data sync --names` sweep; `"refresh"` from the refresh-on-miss resolver (#546, `cli_image`), which writes back the freshly fetched name after a picker miss |
+| `sync.status` | `"missing_remote"` | `DataRepository.mark_asset_missing_remote` — the ghost tombstone, set only when a **complete** remote listing lacks the asset; rows are flagged, never deleted, and tombstoned rows are excluded from later sweeps; cleared automatically if the media reappears in a listing |
+| `sync.checked_at` | UTC ISO timestamp | Same writer — when the absence was last confirmed |
+
+All four are written via single-statement atomic `json_set` updates that
+preserve unrelated metadata keys. See
+[USAGE § `gflow data sync`](USAGE.md#gflow-data-sync).
+
+Two caveats: an in-flight generation's recorder completion can overwrite
+`metadata_json` written concurrently by a sync sweep — self-healing, since the
+row simply re-enters the next sweep. And the nested `sync.*` stamps rely on
+SQLite's `json_set` auto-creating intermediate objects; a very old system
+SQLite (pre-json1 era, roughly < 3.9) may silently no-op them.
+
 ### What is NOT recorded
 
 - Signed CDN URLs (e.g., `fifeUrl?Signature=...`) — they expire and contain bearer-style tokens.

gflow_cli-0.59.0/docs/INDEX.md

@@ -0,0 +1,159 @@
+# Documentation Index
+
+Welcome to the `gflow-cli` documentation. This index is the routing layer: it tells you where each topic lives. Keep `README.md` slim (high-level overview + install) and document deep details here.
+
+| Doc | Purpose | Read when… |
+|---|---|---|
+| [README](../README.md) | Project overview, install, quick start | First time landing on the repo |
+| [docs/DEMOS.md](DEMOS.md) | Gallery of `gflow` in action (terminal + split-screen Flow recordings) | You want to see what gflow looks like running |
+| [AGENTS.md](../AGENTS.md) | Universal coding-agent spec — Cursor / Codex / Aider / Antigravity / Jules / etc. | Any AI coding agent enters the repo |
+| [llms.txt](../llms.txt) | LLM-readable summary (llmstxt.org format) | A user pastes context about gflow into ChatGPT / Claude / Gemini |
+| [docs/PROJECT_STATUS.md](PROJECT_STATUS.md) | Full milestone history + lifecycle policy | Auditing where the project is in its lifecycle |
+| [docs/AGENT_GUIDE.md](AGENT_GUIDE.md) | Mandates and routing rules for AI agents (companion to AGENTS.md) | A coding agent needs the longer non-negotiable rules |
+| [docs/GOVERNANCE_BENCHMARK.md](GOVERNANCE_BENCHMARK.md) | How the advisory materiality gate is measured (false-positive / coverage backtest) and calibrated | You're changing `MATERIAL_PATHS` or auditing whether the governance gate earns its friction |
+| [CLAUDE.md](../CLAUDE.md) | Claude Code's session memory hub (Claude-Code-specific protocol; delegates universal rules to AGENTS.md) | First time Claude Code opens the repo |
+| [PLAN.md](../PLAN.md) | Implementation plan (DDD / CQRS / phases / ADRs) | You want the architectural intent and roadmap |
+| [RELEASE.md](../RELEASE.md) | Release checklist, prerelease policy, PyPI/GitHub publishing protocol | Cutting or auditing a release |
+| [ROADMAP.md](../ROADMAP.md) | Themed milestones from v0.9 through v1.0 | You want a multi-release view of where the project is heading |
+| [CHANGELOG](../CHANGELOG.md) | Version-by-version user-visible changes | Upgrading or auditing what shipped |
+| [KNOWN_ISSUES](../KNOWN_ISSUES.md) | Open / mitigated / resolved issues with workarounds | Before opening a bug report; when something feels off |
+| [DISCLAIMER](../DISCLAIMER.md) | Legal scope, takedown policy, prohibited uses | Before deploying anywhere non-trivial |
+| [LICENSE](../LICENSE) | MIT license text | Always |
+| [CONTRIBUTING](../CONTRIBUTING.md) | TDD workflow, test categories, coverage targets | Before opening a PR |
+| **[docs/DEVELOPMENT.md](DEVELOPMENT.md)** | Branching model, PR protocol, e2e gate, version bump protocol, AI-assisted workflow | Understanding the end-to-end dev process |
+| **[docs/E2E_TESTING.md](E2E_TESTING.md)** | Layer model, cost sub-markers, run commands, isolation patterns, roadmap to contract/replay layer | Running or extending e2e tests; cost control |
+| **[docs/AGENT_UI_E2E.md](AGENT_UI_E2E.md)** | Deterministic e2e runbook for the Agentic UI image path (force-agent trigger, validation ledger) | Live-verifying Agentic-UI features |
+| **[docs/GITHUB.md](GITHUB.md)** | Maintainer PR triage protocol, forked PR handling, SonarCloud scenarios | Reviewing or merging a GitHub PR |
+| [docs/sonar-cleanup-tracker.md](sonar-cleanup-tracker.md) | SonarCloud zero-smells cleanup tracker (`chore/sonar-zero-cleanup`) | Resuming or auditing the Sonar cleanup effort |
+| [docs/medium_tutorial.md](medium_tutorial.md) | Long-form tutorial article (Medium draft): Veo + Imagen from the terminal | Writing or updating outreach/tutorial content |
+| [.env.template](../.env.template) | All environment variables with defaults | Setting up a new shell or container |
+| **[docs/AUTHENTICATION.md](AUTHENTICATION.md)** | Full auth flow, session storage, multi-account, refresh | First `gflow auth login`, or auth errors |
+| **[docs/CONFIGURATION.md](CONFIGURATION.md)** | All env vars, precedence chain, default paths per OS | Tuning behaviour, picking output paths |
+| **[docs/EXTERNAL_STORAGE.md](EXTERNAL_STORAGE.md)** | S3, MinIO, and Google Cloud Storage output configuration | Sending generated assets to a bucket instead of local disk |
+| **[docs/USER_GUIDE.md](USER_GUIDE.md)** | Task-oriented walkthroughs (first setup, batch video, multi-image, log forensics, recovery, multi-account, migration) | You want to GET SOMETHING DONE — not look up a flag |
+| **[docs/USAGE.md](USAGE.md)** | Command-by-command reference, manifest format, recipes, exit-code table | Day-to-day CLI use — look up specific commands / flags |
+| **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** | Modular monolith, per-worker Page pool, RFC 9457 Problem Details, retry layer | Adding a feature or a new provider |
+| **[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/MEDIA_LIBRARY.md](MEDIA_LIBRARY.md)** | Flow's media library as a component: asset-kind taxonomy (`media[]`/`workflows[]`/preset voices), UUID-vs-displayName identity rules (AI caption ≤~35 chars, mutable, async, non-unique), the `projectInitialData` listing endpoint (complete, direct-GET-able), picker UI facts (virtualized grid, per-picker project, no a11y tree, single-click attach) + full pitfall table | Touching any picker/listing/reference code, or debugging why an asset "isn't found" |
+| **[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 |
+| **[docs/MCP.md](MCP.md)** | MCP server: `gflow mcp run` (stdio) + `gflow serve` (Streamable HTTP, SSE deprecated), the tools/prompts/resources surface, the CLI↔MCP parity contract (AGENTS.md "MCP & CLI Schema Symmetry", enforced by `tests/mcp/test_cli_parity.py`), security model, client setup | Configuring an MCP client, working on `gflow_cli.mcp`, or debugging the stdio/HTTP transports |
+| **[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, Antigravity, 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 |
+| [docs/superpowers/specs/2026-07-19-live-verify-design.md](superpowers/specs/2026-07-19-live-verify-design.md) | `/gflow:live-verify` design spec: pre-flight state check + per-feature live-verification gate generalizing release step 4b, council-reviewed | Reviewing or implementing the live-verification enforcement skill |
+| [docs/superpowers/plans/2026-07-19-live-verify/PLAN.md](superpowers/plans/2026-07-19-live-verify/PLAN.md) | Task-by-task implementation plan for `/gflow:live-verify` (skill file → AGENTS.md/check.md wiring → INDEX row) | Tracking task-by-task execution of the live-verify skill |
+| [docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md](superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md) | Edge-case matrix for replacing fixed chain/movie credit estimates with truthful pending-operation guidance | Reviewing the financial-safety, resume, dry-run, and compatibility scenarios |
+| [docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md](superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md) | TDD implementation plan for tier-aware chain/movie planning and confirmation output | Tracking the isolated runtime pricing-guidance bugfix |
+
+## Agent commands
+
+Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixed `/gflow:` to signal project scope and avoid colliding with Claude Code built-ins or user-global commands.
+
+| Command | Purpose | Call when… |
+|---|---|---|
+| `/gflow:check` | Hygiene + auto-fix lint/format + type/test report | Before every commit |
+| `/gflow:status [feature]` | Full state: active plan, progress, next unchecked task | Starting a session; after completing a task |
+| `/gflow:next [feature]` | Next unchecked task only — no context noise | Quick "what do I do right now?" |
+| `/gflow:active` | Which plan is active and its goal — no task detail | Before predict/scenario; quick orientation |
+| `/gflow:plan <feature>` | Create a task-by-task implementation plan → writes `docs/superpowers/plans/` | After predict GO/CAUTION; when a backlog item needs a concrete breakdown |
+| `/gflow:known-issues` | Surface open and mitigated issues | Before touching auth, reCAPTCHA, or previously-flagged code |
+| `/gflow:changelog` | Show `[Unreleased]` entries + last tagged release | Need a quick picture of recent work |
+| `/gflow:release` | Full release flow (calls `/gflow:changelog` + `/gflow:check`) | Cutting a new version |
+| `/gflow:predict <proposal>` | 5-persona pre-implementation analysis → GO / CAUTION / STOP | Before any high-stakes design decision (new transport, auth change, selector redesign, schema migration) |
+| `/gflow:scenario <feature>` | 12-dimension edge-case explorer → severity-ranked scenario table + BDD skeleton | After predict GO/CAUTION; before `/gflow:plan` |
+| `/gflow:pr-council-review [PR#]` | Multi-dimensional council review of an open PR (5 baseline + adaptive dimensions) | Before merging any non-trivial PR; mandatory for auth/transport/data changes |
+| `/gflow:branch-review` | Same council review run against the current local feature branch (no PR needed) | Pre-PR self-audit; after predict/scenario on a high-stakes branch |
+| `/gflow:llm-council [PR#\|--base <ref>] [--tier small\|medium\|high]` | Wraps `pr-council-review` with external CLI reviewers (`codex` + Antigravity `agy`) for cross-model corroboration | High-stakes reviews where a same-model-family blind spot is a real risk |
+| `/gflow:doc-review` | Systematic council-driven audit of documentation completeness and drift | Before cutting a release; after major documentation changes |
+
+**Governance:** commands are executable docs — they decay like any doc. When a phase advances or a file path changes, update the relevant command in the same commit. `/gflow:release` includes a staleness review step.
+
+## Topic shortcuts
+
+**"What's the governance flow, and which paths require predict/council?"** → [AGENT_GUIDE § Governance & Enforcement](AGENT_GUIDE.md#governance--enforcement)
+**"Why did the materiality advisory flag my PR?"** → [AGENT_GUIDE § Materiality coverage](AGENT_GUIDE.md#materiality-coverage-path--recommended-gate)
+**"I just installed gflow — how do I get to my first video?"** → [USER_GUIDE § Journey 1](USER_GUIDE.md#journey-1--first-time-setup-10-minutes)
+**"How do I render 20 clips overnight?"** → [USER_GUIDE § Journey 3](USER_GUIDE.md#journey-3--batch-video-from-a-prompt-list-shell-loop)
+**"How much will this batch cost me in Veo credits?"** → [USER_GUIDE § Journey 10](USER_GUIDE.md#journey-10--budgeting-credits-before-a-batch-run)
+**"How do I feed gflow outputs into ffmpeg / a pipeline?"** → [USER_GUIDE § Journey 11](USER_GUIDE.md#journey-11--wiring-gflow-outputs-into-a-downstream-pipeline)
+**"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 does Flow's media library / picker actually behave (names, tabs, scrolling, listing)?"** → [MEDIA_LIBRARY](MEDIA_LIBRARY.md) — identity = UUID, names are async AI captions; grid is virtualized; full pitfall table
+**"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)
+**"What preset voices can a character use?"** → run `gflow character voices` — see [USAGE § `gflow character voices`](USAGE.md#gflow-character-voices)
+**"My batch run died with exit code 3 (auth) — what now?"** → [USER_GUIDE § Journey 7](USER_GUIDE.md#journey-7--recovering-from-an-authexpirederror-mid-run)
+**"Exit code 4 (rate-limit) or 5 (content-policy) — how do I recover?"** → [USER_GUIDE § Journey 12](USER_GUIDE.md#journey-12--recovering-from-contentpolicyerror-or-ratelimiterror)
+**"How do I read the structured log (`error_raised` events)?"** → [USER_GUIDE § Journey 6](USER_GUIDE.md#journey-6--reading-structured-logs-jq-recipes)
+**"What exit code does shell branching see for each error class?"** → [USAGE § Exit codes](USAGE.md#exit-codes)
+**"Is `v0.5.0a1` a prerelease, and how do I cut a full release?"** → [RELEASE § Prerelease Versus Full Release](../RELEASE.md#prerelease-versus-full-release)
+**"Where is my session stored?"** → [AUTHENTICATION § Session storage](AUTHENTICATION.md#session-storage)
+**"Where do generated files land?"** → [CONFIGURATION § Output paths](CONFIGURATION.md#output-paths)
+**"How do I write outputs to S3, MinIO, or Google Cloud Storage?"** → [EXTERNAL_STORAGE](EXTERNAL_STORAGE.md) and [CONFIGURATION § `GFLOW_CLI_STORAGE_URI`](CONFIGURATION.md#gflow_cli_storage_uri)
+**"How do I run with multiple Google accounts?"** → [AUTHENTICATION § Multiple accounts](AUTHENTICATION.md#multiple-accounts)
+**"How do I know which Google account a profile is signed into?"** → [AUTHENTICATION § gflow auth list](AUTHENTICATION.md#gflow-auth-list)
+**"Why is my profile named 'default' and how do I rename it?"** → [AUTHENTICATION § Profile naming](AUTHENTICATION.md#profile-naming)
+**"How does login verification work without launching a browser?"** → [AUTHENTICATION § Session verification](AUTHENTICATION.md#session-verification-cookie-store-fast-path) (cookie-store fast path, v0.17.0)
+**"How does the layered structure work?"** → [ARCHITECTURE § Layers](ARCHITECTURE.md#layers)
+**"What env var should I set for X?"** → [CONFIGURATION § Reference](CONFIGURATION.md#reference)
+**"What does gflow remember after a generation finishes?"** → [DATA_LAYER § What is recorded](DATA_LAYER.md#what-is-recorded)
+**"How do I see what's in my gflow catalog?"** → run `gflow data list projects` (or `images` / `videos` / `profiles`) — see [DATA_LAYER § Querying the data layer](DATA_LAYER.md#querying-the-data-layer)
+**"Where can I look up a media ID I generated yesterday?"** → [DATA_LAYER § Querying the data layer](DATA_LAYER.md#querying-the-data-layer)
+**"How do I stop gflow from storing my prompts?"** → [DATA_LAYER § Privacy and redaction](DATA_LAYER.md#privacy-and-redaction)
+**"What does exit code 16 mean and how do I recover?"** → [DATA_LAYER § Persistence-failure handling](DATA_LAYER.md#persistence-failure-handling)
+**"Is my install/catalog healthy?"** → run `gflow doctor` (read-only, never migrates; exit 33 = findings present) — see [USAGE § `gflow doctor`](USAGE.md#gflow-doctor)
+**"My old assets re-upload / have no names?"** → run `gflow data sync --names` (credit-free name backfill from Flow's listing) — see [USAGE § `gflow data sync`](USAGE.md#gflow-data-sync)
+**"How do I use this project's skills in Cursor / Codex / Antigravity / Aider?"** → [skills/README.md](../skills/README.md#use-with-other-agents)
+**"How do I benchmark a skill doc against real tasks?"** → [scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)
+**"How do I compare Claude vs GPT-4o vs Gemini on gflow tasks?"** → `python scripts/dev/skillopt/harness.py --provider openai --model gpt-4o` (see [skillopt README](../scripts/dev/skillopt/README.md))
+**"What does Chrome actually use in RAM during a generation?"** → run `uv run python scripts/diag/memory_profile.py --profile NAME` (see [scripts/diag/README.md](../scripts/diag/README.md))
+**"How do I report a security issue?"** → [SECURITY § Reporting](SECURITY.md#reporting)
+**"What branch do I work on? How do I name it?"** → [DEVELOPMENT § Branching model](DEVELOPMENT.md#branching-model)
+**"How do I handle an external GitHub PR?"** → [GITHUB § Scenario Matrix](GITHUB.md#scenario-matrix)
+**"What automation runs on external PRs?"** → [GITHUB § Automated External PR Triage](GITHUB.md#automated-external-pr-triage)
+**"How do we use Copilot review on PRs?"** → [GITHUB § GitHub Copilot Code Review](GITHUB.md#github-copilot-code-review)
+**"Why did SonarCloud skip or fail on a forked PR?"** → [GITHUB § Forked PRs And SonarCloud](GITHUB.md#forked-prs-and-sonarcloud)
+**"How do I run e2e tests before a release?"** → [DEVELOPMENT § E2e gate](DEVELOPMENT.md#e2e-gate-before-merging-develop--main)
+**"What does each e2e marker cost? How do I run only the cheap tests?"** → [E2E_TESTING § Run commands](E2E_TESTING.md#run-commands)
+**"When does the version get bumped?"** → [DEVELOPMENT § Version bump protocol](DEVELOPMENT.md#version-bump-protocol)
+**"How do I embed FlowApiClient in a long-lived worker / service?"** → [USER_GUIDE § Journey 14](USER_GUIDE.md#journey-14--embedding-flowapiclient-in-a-long-lived-worker)
+**"What's the standard way to import gflow errors in my code?"** → [USAGE § Programmatic use](USAGE.md#programmatic-use)
+**"gflow refuses to open my profile after a downgrade (exit 11, 'written by a newer Chromium')"** → [AUTHENTICATION § Chromium downgrade guard](AUTHENTICATION.md#chromium-downgrade-guard)
+**"Two gflow runs on the same profile — can the second one wait instead of failing (exit 11)?"** → [CONFIGURATION § GFLOW_CLI_LEASE_WAIT_SECONDS](CONFIGURATION.md#gflow_cli_lease_wait_seconds) (v0.56.0 opt-in bounded wait)
+**"How do I silence the 'newer version on PyPI' stderr notice?"** → [CONFIGURATION § GFLOW_CLI_UPDATE_CHECK](CONFIGURATION.md#gflow_cli_update_check) (`0` disables; auto-skipped in CI and for editable installs)
+**"How do I run the MCP server so an agent can't spend credits?"** → [CONFIGURATION § GFLOW_MCP_NO_SPEND](CONFIGURATION.md#gflow_mcp_no_spend) + [MCP § Option A2](MCP.md#option-a2-read-only-server) (`gflow mcp run --no-spend` / `GFLOW_MCP_NO_SPEND=1`; v0.57.0 — both generate tools go unregistered, not merely refused)
+**"Which Flow UI arm does a video run require, and why did it exit 2 or 28?"** → [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode) (v0.57.0 — video is classic-only: `auto` ≡ `classic`, explicit `agentic` exits 2, unreachable classic aborts pre-submit with exit 28, $0)
+**"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
+**"A command failed — where is the incident bundle and what's in it?"** → [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) (layout, triggers, review-before-sharing); privacy boundaries: [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on); disable via [CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE](CONFIGURATION.md#gflow_cli_incident_capture)
+**"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.59.0](LIVE_VERIFICATION_v0.59.0.md) (**#542 doctor + #543 data sync + #546 refresh-on-miss, verified 2026-08-16 on profile `denon82`, ~4 Imagen credits** — doctor offline-verified (byte-identical never-writes proof); sync live-verified by a zero-credit e2e AND a real 117-project backfill (398 nameless rows → 338 named / 57 tombstoned / 0 failures); refresh-on-miss live-healed a deliberately-corrupted catalog name mid-generation via picker attach with `sync.source=refresh`); previously: [LIVE_VERIFICATION_v0.58.0](LIVE_VERIFICATION_v0.58.0.md) (**#529 catalog-UUID→displayName picker contract + r2v named-reference fixes, verified 2026-08-15/16 on profile `denon82` (pt-BR) via four committed e2e tests, ~7 Imagen + 1 veo-lite generation** — same-project exact-UUID tile attach, cross-project verified upload fallback, loud abort on unresolvable UUIDs, and a real r2v video generated from a catalog name; the r2v e2e caught and fixed two live UI drifts: the picker exposes no accessible tree so tiles are now text-matched, and a tile click attaches directly with the include button demoted to legacy fallback); previously: [LIVE_VERIFICATION_v0.57.1](LIVE_VERIFICATION_v0.57.1.md) (**#493 and #451/#288 root-caused and fixed from live evidence, verified 2026-08-14 on profile `denon82` (pt-BR — the #493 reporter's locale), ZERO credits** — #493 was NOT an unrecognized "third editor variant": "Inicial"/"Final" are the Frames sub-mode's Start/End slots and the "Agente" pill is the ordinary Agent button, both stock classic features. The real trigger is Flow's **expanded chat sidebar**, which removes the classic composer entirely [`crop_* = 0` AND `Agent pill = 0` simultaneously] — one state producing both reported symptoms, and the reason the failure was exit 23 rather than the retryable 25 [no agentic indicator on screen, so the cohort detector matched nothing]. Recovery hinged on a close button scoped to the sidebar's `edit_square` affordance, a single point of failure for any cohort lacking that ligature; an unscoped fallback now fires only from the demonstrably stuck state, **A/B-proven three ways** [scoped broken + fallback present → rescued; both broken → NOT recovered, which is what proves the fallback rescues rather than the surrounding loop]. #451/#288 were never selector drift either — Flow's settings popover is **model-conditional**, only `omni-flash` renders a duration row, so `--duration` on a Veo model hunted a control that is never drawn [verified on 2 accounts × 2 locales]; it now exits 2 before any browser work. Two #493 hypotheses were tested and **refuted** first and are committed so they are not re-derived [a `crop_free` sub-mode trigger — the trigger reflects the *aspect*, not the sub-mode; and a hydration race — a wait was written, A/B-neutered, and cold loads passed 3/3 BOTH ways, so it was reverted rather than shipped]. Recorded not-verified: the `veo_3_1_lite_lower_priority` picker miss is **inconclusive** [the capture came after the menu closed] so that selector was deliberately left untouched, and `chain.py`'s per-link duration aborts mid-run after billing — deferred with the finding recorded). Prior: [LIVE_VERIFICATION_v0.57.0](LIVE_VERIFICATION_v0.57.0.md) (**#299 video UI-mode policy + the #496/#497/#498/#501 MCP wave live-verified 2026-08-14 on profile `ffroliva`, ZERO credits** — three real video-editor loads bound the classic driver through `get_ui_driver` [`ui_driver.bound mode=classic`, 1.2–1.7 s, aborted pre-submit], `--ui-mode agentic` is refused with **exit 2 before any browser launch** [deliberately not exit 28, whose "retry may land it" hint would mislead for a driver that does not exist], and a real-editor classic→agent→classic round-trip proved `ensure_agent_mode`'s aria-verified real click [`{"agent_acted":true,"after_agent":"agent","after_media":"media"}`]; the MCP surfaces were driven over the **real stdio JSON-RPC wire** [subprocess `gflow mcp run`, so registration *and* stream routing are covered]: `--no-spend` cut `tools/list` from 11 tools to 9 with both generate tools genuinely unregistered rather than refused, zero-arg `gflow_auth_status` returned `authenticated` off a live `GET /fx/api/auth/session` **200**, `gflow_list_projects` returned **different project IDs** on offset 0 vs offset 2 [proving the offset is honored — catalogs larger than `limit` were previously unreachable] with `limit=0`→1 and `offset=-5`→0 clamps holding, and the known-issues resource served a **7,543-byte index** against a ~70 KB source file with a **111-byte** capped unknown-slug reply. The #498 rate-limited problem-details envelope is recorded **not live-verified with reason** — exhausting the token bucket needs ≥9 accepted generate calls, so the error path cannot be reached credit-free; it is unit-pinned for both tools instead). Prior: [LIVE_VERIFICATION_v0.56.0](LIVE_VERIFICATION_v0.56.0.md) (**#477 downgrade guard, #478 bounded lease wait, and the #493 mode-switch path live-verified 2026-08-13 on profile `denon82`, images only** — a fresh-project 16:9 `t2i` exercised the #493-touched mode-switch path end-to-end [valid `ff d8` JPEG 1376×768, `image_mode_entered` → `batch_response_captured`]; the #477 guard refused a scratch profile claiming Chromium 999 with **exit 11 pre-auth, pre-credits** at the generation-client call site; #478 was proven with three concurrent runs — `WAIT=0` control failed fast with `ProfileLockedError` exit 11 while the holder held, and the `WAIT=180` waiter polled ~11 s past the holder's natural release then generated successfully; the #493 drift branch itself is a named skip [only an affected account's new-editor cohort can reach it — the fix's message text is unit-pinned], and #479's update notice is deferred-with-reason to a post-release check [it needs a published newer version on PyPI and skips editable installs by design]; an expired denon82 session 401'd the first two attempts [external state, re-login fixed it, recorded not omitted]). Prior: [LIVE_VERIFICATION_v0.55.0](LIVE_VERIFICATION_v0.55.0.md) (**Tier-1 quick wins #471–#476 verified 2026-08-13 on profile `ffroliva`, ZERO credits** — `gflow auth status` probed the real Flow session endpoint live [`Flow session verified as ffroliva@gmail.com.`, exit 0, fail-closed contract pinned]; `gflow mcp setup` ran end-to-end with the real CLI against a scratch copy of the real Claude Desktop config [correct merged entry, pristine original]; the Windows profile-DACL two-step `icacls` idiom was derived empirically [the naive `/t` form broke file access] and is pinned by a real-icacls round-trip test on every Windows host; the incident bug-report template, MCP error funnel [all 11 tools guarded, raw exception text masked], and SecretStr settings are suite-verified with no live-Flow surface — reasons recorded, not omitted). Prior: [LIVE_VERIFICATION_v0.54.0](LIVE_VERIFICATION_v0.54.0.md) (**close-browser guidance #470, character-composer focus fix, overlay/jitter hardening, and SonarCloud-S2245 RNG swap live-verified 2026-08-12 on profile `ffroliva`, ZERO credits** — the new #470 login wording printed verbatim and the manual-close → `auth_flow_session_verified` round-trip worked end-to-end; a Classic-UI `t2i` produced a real 1024×1024 JPEG [`ff d8 ff e0`] exercising overlay dismissal + jitter + image-composer submit + mode controller, and a credit-free `character create` [entity `da3cd647…`, face 1376×768 JPEG] exercised the character-composer path directly [`entering_character_editor` → `prompt_submitted` → `entity_patched` → `completed`]; the first `t2i` hit the known agentic-cohort video-for-image condition [correctly refused via `WireFormatError`, tracked by #299, not a regression] and Classic UI worked around it. First mainline release after the orphaned v0.53.0/v0.53.1 tags — CHANGELOG restores honest 0.53.x sections). Prior: [LIVE_VERIFICATION_v0.52.0](LIVE_VERIFICATION_v0.52.0.md) (**batch DAG references #317, character entity provenance recording #402, and video duration selector cascade fix #451 live-verified 2026-08-05** — 3/3 live E2E tests in `tests/e2e/test_entity_provenance_e2e.py` passed clean on profile `ffroliva`, 5-layer evidence ledger verified). Prior: [v0.51.0](LIVE_VERIFICATION_v0.51.0.md) (**dependency/security/test-correctness release verified 2026-08-05, 1 Imagen credit + 1 Veo attempt** — the only change needing live evidence was the `playwright` bound raise `>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0`, and the 2026-08-03 regression does NOT reproduce on 1.61.0: a live i2v drove `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live i2i local-ref attach passed outright [96.7s]. **1.62.0 stays excluded**, never root-caused. `-m e2e_auth` 16/16, daemon e2e 1 passed [MCP over Streamable HTTP — the first live coverage that test has ever had, it was structurally incapable of passing before], MCP Tasks 5/5 layers, 2923 offline tests, `pip-audit --all-extras` clean. **No finished mp4 is claimed** — Flow's own generation returned `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT`, server-side. Defect found and recorded not omitted: Flow dropped the duration-tab UI so **`--duration` is currently broken for i2v**, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0 — [#451](https://github.com/ffroliva/gflow-cli/issues/451)). Prior: [v0.50.0](LIVE_VERIFICATION_v0.50.0.md) (**MCP Tasks extension SEP-2663, non-blocking task handle responses, CLI/MCP output path hardening -o/--output, and Telegram PR triage alert resilience verified 2026-08-04** — 5-layer evidence ledger note generated at `tmp/live-verify/mcp-tasks.md` confirming instant task handle return, working status queries, and cancelled status DB state transitions; full 118-test suite green). Prior: [v0.49.0](LIVE_VERIFICATION_v0.49.0.md) (**#125 `omni-flash` start-frame I2V video generation, Playwright dependency upper-bound pin `>=1.59.0,<1.60.0`, submission stage watchdog timeout, and #404 count-tab fail-closed logic verified 2026-08-03** — 0-credit wire intercept captured `batchAsyncGenerateVideoStartImage` with `startImage` bound; live costed generation on `omni-flash` I2V produced a 1.2MB valid mp4 video asset on `ffroliva`; full 2902-test release suite green). Prior: [v0.48.0](LIVE_VERIFICATION_v0.48.0.md) (**#411 predictable `-o`/`--output` paths, offline-verified 2026-08-02, ZERO credits** — exact single-target local writes + `_1`/`_2` multi-count **image** suffixes proven by the CLI suite; the pre-tag council audit [RED, then resolved] re-scoped the release to the truthful surface: a dead MCP `output` param was deleted [worker queue never read it — #414], cloud `-o` targets and video multi-count suffixes are follow-ups [#415], and two tautological video-path tests are recorded as weak evidence rather than claimed as proof; storage-layer S3 writes verified against Docker MinIO at the layer level only; 2888-test release tree green; the live-Flow run aborted pre-generation on an expired denon82 session [`AuthExpiredError` 401, correct RFC-7807 contract + remediation hint, $0] — recorded, not omitted; live re-run queued for the next authenticated session). Prior: [v0.47.0](LIVE_VERIFICATION_v0.47.0.md) (**MCP SDK 2.0.0 migration + dual-era protocol + #402 entity provenance recording live-verified 2026-08-01, ZERO credits** — stdio JSON-RPC initialization handshake verified over subprocess transport, `resolve-drift` CI job added to prevent dependency drift, and 121 unit tests in `tests/data` passed). Prior: [v0.46.1](LIVE_VERIFICATION_v0.46.1.md) (**#404 classic count-setter fix live-verified 2026-07-31 on the reporter's exact environment, ZERO credits** — credit-free DOM recon proved Flow renamed the count-tab labels to uniform `xN` [`x1` replaces `1x`, image AND video rows], that `nth(0)` of the old filtered set landed on the selected `x2` and actively moved the count AWAY from the target, and that a digit-keyed click on `x1` converges instantly and persists without a Save commit; the new classic e2e then passed live [count=1 against a fresh project displaying 2 → exactly 1 image; count=2 early-exit → exactly 2], and the #313 agentic count-enforcement e2e passed 4/4 [counts 1–4 vs deliberately mismatched sticky defaults, magic-byte-verified downloads] after its stale setup was repaired [Flow now loads the editor in classic mode — the setup needed an Agent-pill toggle before the `tune` icon; test-only fix, no product code implicated]; the video output-count cascade carries a recorded waiver [full drive costs Veo credits; its exact selector shape was exercised live in the spike's cleanup step]). Prior: [v0.46.0](LIVE_VERIFICATION_v0.46.0.md) (**#387 provider-agnostic prompt-tools transport live-verified 2026-07-28, ZERO credits** — a four-probe capability spike passed 4/4 against BOTH a non-Google gateway and Google's OpenAI-compat endpoint, including a *semantic* multimodal check [a generated solid-red JPEG round-tripped and the model answered 'Red'], which is what proved the native Gemini `inlineData` path could be deleted outright rather than kept as a fallback; the real CLI then returned `was_expanded: true` on gateway/gateway-no-model/Google-default, emitted the loud one-time notice + no-op for the removed `GFLOW_CLI_GEMINI_API_KEY`, and made NO network call when unconfigured. Live verification caught two defects a fully green 2849-test offline suite missed: Google's compat endpoint has no server-side default model [`400 "model is not specified"`, silently no-oping the DEFAULT configuration], and the first redirect guard did not actually work because `build_opener()` installs its default handlers regardless of arguments, so `Authorization` would still have been replayed cross-host. `/code-review high` is recorded as NOT run — it is user-triggered only). Prior: [v0.45.0](LIVE_VERIFICATION_v0.45.0.md) (**#393 UUID `--ref` binding + #395 character-entity binding live-verified 2026-07-27/28** — a controlled A/B on identical input flipped `--ref` from exit 9 to exit 0 via the catalog-backed upload fallback, with the anti-silence guard [an unbindable ref aborts non-zero and writes no image] pinned by a live e2e; picker DOM + HAR showed Flow indexes a short auto-caption, NOT the prompt, so a prompt-derived search hint was dropped rather than shipped on assumption; a CDP spike against Flow's own character flow then captured the `entityContext` contract that gflow's generations were missing, root-causing #395 to two gflow defects [overlay dismissal Escaping Flow's own composer, and a character-route bounce that sent the prompt to the project composer] — both fixed, both character e2e tests now pass live, including `--format-prompt` [#383], with a read-back confirming the character carries its name and `thumbnail_media_id`). Prior: [v0.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [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)
+**"Was the playwright upper bound raised, and on what evidence?"** → [LIVE_VERIFICATION_playwright_1.61](LIVE_VERIFICATION_playwright_1.61.md) (**`>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0` verified 2026-08-05, 1 Imagen + 1 Veo credit** — the 2026-08-03 regression that motivated the bound does NOT reproduce on 1.61.0: a live `i2v` drove the full chain with `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live `i2i` local-ref attach passed outright [96.7s]. **1.62.0 stays excluded** — never root-caused. Also found, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0: Flow dropped the duration-tab UI, so **`--duration` is currently broken for i2v** — `UiSelectorDriftError` fires correctly [refusing rather than silently accepting Flow's default, #288] but the selector needs re-deriving; that is why the i2v proof was driven via the CLI without `--duration`, and Flow's own server-side `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT` means no finished mp4 is claimed).
+**"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)
+
+## Documentation governance
+
+- `README.md` is for first-time visitors. Keep it under ~400 lines. Anything longer belongs in `docs/`.
+- Every new behaviour or env var needs a row in this index AND a section in the relevant `docs/*.md`.
+- Cross-link generously. Use markdown link syntax with an anchor wherever a reader might need to jump deeper — they should never get stuck.
+- Keep file size sane. If `docs/USAGE.md` grows past ~600 lines, split into `docs/USAGE/<topic>.md`.

{gflow_cli-0.58.0 → gflow_cli-0.59.0}/docs/LIVE_VERIFICATION_v0.58.0.md

@@ -89,5 +89,8 @@ the caption asynchronously, so a fresh generation may record without a
 
 ## Post-tag evidence
 
-_To be filled after the v0.58.0 tag publishes: release workflow run link, PyPI
-listing, and `pipx install gflow-cli==0.58.0` smoke check._
+- Release workflow: [run 31934310984](https://github.com/ffroliva/gflow-cli/actions/runs/31934310984)
+  — **success**, digital attestations generated and uploaded.
+- GitHub Release: `v0.58.0` published 2026-08-16T07:37:15Z, stable (not draft,
+  not prerelease).
+- PyPI: `gflow-cli` latest = **0.58.0** (JSON API confirmed post-publish).

gflow_cli-0.59.0/docs/LIVE_VERIFICATION_v0.59.0.md

@@ -0,0 +1,66 @@
+# Live verification — v0.59.0
+
+> Hand-run against real Flow on Windows 11, profile `denon82` (chrome strategy,
+> pt-BR), 2026-08-16, during Phase D/S/R development on
+> `feature/542-546-doctor-sync-refresh`. Doctor is offline (unit fixtures are
+> its evidence); sync and refresh-on-miss were live-verified end to end.
+> Credits spent: ~4 Imagen (two seed/heal pairs across refresh-on-miss e2e
+> runs); sync verification was **zero-credit** (listing endpoint only).
+
+## Environment
+
+| | |
+|---|---|
+| Branch | `feature/542-546-doctor-sync-refresh` (off `develop` @ v0.58.0) |
+| Profile | `denon82` (pt-BR) |
+| Date | 2026-08-16 |
+| OS | Windows 11 |
+| Credits spent | ~4 Imagen + 0 Veo |
+
+## Pre-tag gates
+
+- Full four-dir suite on the finished tree: **2,088+ passed** (tests/cli,
+  tests/api, tests/services, tests/data, tests/mcp), `pyright src` 0 errors,
+  ruff clean, all doc gates green (mirror `--check`, links, PII, hygiene).
+- Every task shipped through the subagent implement → spec-review →
+  quality-review loop (14 plan tasks + S6b hardening + 3 review-fix commits);
+  two live-caught bugs fixed with red-first regression tests (sqlite
+  cross-thread store open; MagicMock project-id leak past an `is None` guard).
+
+## Matrix
+
+| # | Feature | Verification | Result |
+|---|---|---|---|
+| 1 | `gflow doctor` (#542) | Offline by design — 33 unit tests over migration-built fixture DBs incl. the byte-identical never-writes proof; real-output smoke run during review (grouped report, caveat, exit 33) | ✅ |
+| 2 | `gflow data sync --names` (#543) e2e | `tests/e2e/test_data_sync_names_e2e.py` (zero credits): seeded name-stripped rows + fabricated ghost against a real project → names restored with `sync.named_at`/`sync.source="sync"`, ghost tombstoned `missing_remote`, idempotent re-run byte-identical | ✅ 1 passed, 9.7 s |
+| 3 | Sync at real scale | **Real catalog backfill**: 117 projects swept in ~4 min, zero failures — 398 nameless rows → **338 named, 57 tombstoned, 3 left** (async captions; retry harmlessly). Dry-run first (50 projects, counts matched) | ✅ |
+| 4† | Refresh-on-miss (#546) e2e | `tests/e2e/test_refresh_on_miss_e2e.py` (~2 credits/run): seed t2i → catalog name deliberately corrupted (simulated rename) → same-project `i2i --ref` → picker miss → resolver fetched the true caption mid-generation → `image_ref_selected_existing`, no upload fallback, no `name_resolver_failed`, catalog healed with `sync.source="refresh"` | ✅ 1 passed, 100 s (first attempt failed on transient live-Flow timing; clean pass on re-run) |
+
+† i2v frame refresh shares the same `_select_existing_asset` path; live-covered
+via i2i, i2v plumbing unit-tested.
+
+## 5-layer ledger (refresh-on-miss, the deepest chain)
+
+1. **File count** — one generated image from the heal run in the isolated out dir.
+2. **Magic bytes / artifact** — generation completed through the normal
+   download path (exit 0, `--json` payload with `ref_count == 1`).
+3. **Shape** — `image_ref_selected_existing` with `resolved_by=display_name`
+   after a first-search miss on the corrupted name.
+4. **Structlog invariants** — no `image_ref_upload_fallback`, no
+   `name_resolver_failed`; healed row carries `display_name == real Flow
+   caption` + `sync.source == "refresh"`.
+5. **User-confirmable artifact** — the referenced asset and the new generation
+   are visible in the `denon82` Flow project.
+
+## Known live behaviors recorded
+
+- Flow captions remain async: 3 real catalog rows stayed nameless after the
+  full backfill — expected; they re-enter the next sweep.
+- One transient heal-run failure on live Flow (timing); deterministic on
+  re-run. The e2e's seed retry (2 attempts) covers the caption race; the heal
+  step has no retry by design — a rerun is the operator remedy.
+
+## Post-tag evidence
+
+_To be filled after the v0.59.0 tag publishes: release workflow run link, PyPI
+listing._