gflow-cli 0.28.0__tar.gz → 0.30.0__tar.gz

gflow_cli-0.30.0/.claude/commands/gflow/check.md

@@ -0,0 +1,78 @@
+---
+description: Auto-fix lint and formatting, then report types and tests. Run before every commit.
+---
+
+# `/gflow:check` — Quality gates
+
+Run in order. Stop and report if a step fails after the fix pass.
+
+## Steps
+
+These steps mirror the CI `test` job in `.github/workflows/ci.yml` **in the same order**. Any command that CI runs as a *verify* (`--check`) is run here as a verify too — see step 4.
+
+**1. Repo hygiene + doc links** (read-only — CI runs both; a broken doc link fails CI)
+
+```bash
+PYTHONUTF8=1 uv run python scripts/ci/check_repo_hygiene.py
+PYTHONUTF8=1 uv run python scripts/ci/check_doc_links.py
+```
+
+**2. Auto-fix lint and formatting** (rewrites files in place)
+
+```bash
+uv run ruff check --fix src tests
+uv run ruff format src tests
+```
+
+Report which files were modified. **If this rewrote anything, those files are part of the change — stage them.** CI does not run the auto-fix; it runs the `--check` verify in step 4 against the *committed* tree, so an uncommitted reformat is a red CI build.
+
+**3. Repeat lint/format ONLY on the files you touched? No — always run repo-wide.** The whole-tree `src tests` scope in step 2/4 is deliberate: a latent format failure in a file your change merely imports (e.g. a BDD step module) will fail CI even if your own edits are clean. Never narrow the scope to "just my files."
+
+**4. Verify — the EXACT CI gate (non-mutating; must be clean before you commit/push)**
+
+```bash
+uv run ruff check src tests
+uv run ruff format --check src tests
+```
+
+These are byte-for-byte what CI runs (`ci.yml` "Lint" + "Format check"). If `--check` exits non-zero here, step 2's rewrites are **uncommitted** — stage them and re-run. **Never push while this is red:** the test job dies at the format step *before* pytest, which also makes SonarCloud report `new_coverage=0%` (no coverage XML is produced). A green `/gflow:check` that skips this verify is how PR #269 shipped a format failure past an 8-agent council.
+
+**5. Type check** (report only — cannot auto-fix)
+
+```bash
+uv run pyright src
+```
+
+**6. Tests + coverage** (report only)
+
+```bash
+uv run python -m pytest -q --cov=gflow_cli --cov-fail-under=80
+```
+
+## Output
+
+- List files changed by the fix pass (empty = nothing needed fixing)
+- **Step 4 verify result — `ruff check` + `ruff format --check` both clean (this is the CI gate; a non-zero here is a blocking finding, not a warning)**
+- All pyright errors with `file:line` references
+- Pytest summary line and coverage percentage
+- Final verdict: all gates pass / which gates failed
+
+## Notes
+
+Ruff fix and format may rewrite multiple files. Always `git diff` before staging.
+Pyright errors and test failures require manual intervention — do not attempt silent workarounds.
+If the coverage run crashes the current MCP/sandbox session with `Connection closed`, re-run the
+same marker-filtered suite in smaller chunks without coverage and rely on CI for the coverage XML.
+Project pytest defaults already exclude `e2e` and `live`; those markers are explicit,
+credit-spending gates and must be requested with a separate `-m e2e` / `-m live` command.
+
+**Windows agent sessions:** `uv run pytest` is unreliable — invoke
+`.venv/Scripts/python.exe -m pytest` directly, and prefix Python invocations with
+`PYTHONUTF8=1` when output contains non-ASCII. The unscoped full-coverage sweep
+(step 6) can OOM locally (exit 137 / SIGKILL): run the suites scoped to the dirs you
+touched and trust CI for the full coverage gate — **a green full-suite CI run on the
+same tree (e.g. the just-merged PR) satisfies step 6 for release purposes.**
+
+The OOM allowance applies to step 6 (coverage) ONLY. Step 4 (`ruff check` + `ruff
+format --check src tests`) is cheap, never OOMs, and must ALWAYS be run repo-wide
+against the exact tree you are about to push — no scoping, no skipping.

{gflow_cli-0.28.0 → gflow_cli-0.30.0}/AGENTS.md

@@ -8,8 +8,8 @@ Supported tools that auto-discover this file: Cursor, Codex, Aider, Jules, Devin
 
 - Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
-- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_models.py`, `cli_run.py`, `cli_scene.py`, `cli_video.py`, `config.py`, `data/`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
-- Command surface: `gflow auth`, `gflow image` (t2i/i2i/upload), `gflow video` (t2v/i2v/r2v/batch/chain), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), and `gflow data` (catalog queries).
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `composition.py`, `config.py`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/batch/chain), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (HTTP/SSE).
 - Requires a Google AI Ultra or Pro subscription with Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)
@@ -57,9 +57,9 @@ 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–22, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`). 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–25, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
-- **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_server.py`.
+- **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`.
 
 ## PR instructions
 

{gflow_cli-0.28.0 → gflow_cli-0.30.0}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] — 2026-07-09
+
+### Added
+
+- **MCP `gflow_generate_video` model/duration/count parameters (CLI↔MCP parity):** agents can now select the Veo model (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), clip duration, and batch count through MCP, matching the CLI `gflow video` flags. An unknown model is rejected up front with a 400 instead of failing deep in the worker; an omitted model still lets the transport apply its i2v veo-lite default (issue #125). Co-authored-by C1ph3r404 (from the closed PR #258). Note: the pre-existing transport-level i2v veo-lite default already protected the MCP path, so this is parity + agent control, not a new credit guard.
+
+### Fixed
+
+- **Character-create recorder no longer crashes on a duplicated `flow_media_id`.** Under the agentic cohort the classic character-editor slot-add control is absent, so the body prompt lands in the still-active face slot and both slots report the same `flow_media_id`; `_record_character_local_files` minted a fresh asset `id` per slot and the second slot violated `UNIQUE(profile_name, flow_media_id)` → `DataIntegrityError`. The recorder now reuses the existing asset id (mirroring `record_completed_video`), making character local-file recording idempotent on the business key. Regression test in `tests/data/test_recorder_character.py`.
+- **`prefer_classic` no longer logs a misleading `WARNING` on the agentic cohort.** The server-gated agentic (`tune`) cohort cannot be exited client-side, and `prefer_classic` is best-effort by contract, so `get_ui_driver` now logs that expected fall-through at `INFO` (`ui_driver.prefer_classic.cohort_natively_agentic`) and reserves `WARNING` for genuinely unexpected exit failures.
+
+## [0.29.0] — 2026-07-09
+
+### Added
+
+- **Persistent `gflow instructions` command group:** CRUD over project brief cards (add, list, enable, disable, rm, apply, toggle-mode) with title/ID selection, master toggle, and REST upload support for card reference images. Live-verified credit-free end-to-end (see `docs/LIVE_VERIFICATION_v0.29.0.md`).
+- **Declarative full-sync:** `gflow instructions apply FILE` for idempotent sync of instructions from TOML or JSON brief files.
+- **Movie manifest instructions integration:** Global `[instructions]` and per-scene `[scenes.instructions]` blocks in `movie.toml` to dynamically sync project brief cards before generating clips (per-scene re-sync memoized via `_BriefSyncCache`; documented as a destructive full-sync).
+- **`gflow_instructions_*` MCP tools:** six new tools (`list`, `add`, `set_enabled`, `rm`, `toggle_mode`, `apply`) giving MCP agents the full instructions CRUD surface — thin adapters over the same live-verified brief primitives, credits-free, RFC 9457 error envelopes. `gflow_list_tools` and the new tools are now documented in `docs/MCP.md`. Note: `gflow_generate_video` deliberately has no `instructions` param (the video pipeline has no instructions support — documented asymmetry).
+- **MCP↔CLI parity contract enforced in CI:** `tests/mcp/test_cli_parity.py` walks every CLI leaf command and fails when one has neither a mapped MCP tool nor an explicit, reasoned exemption.
+
+### Changed
+
+- **Agentic-indicator selectors consolidated:** the 4 agentic cohort ligature probes are now canonical in `drivers/factory.py` (`AGENTIC_INDICATOR_SELECTORS`, `AGENT_TUNE_INDICATOR_SELECTOR`); both UI transports import them instead of carrying drift-prone copies, locked by a new symmetry test.
+
+### Internal
+
+- **`/gflow:check` and the PR council are now CI-faithful:** the check gate runs the exact CI verify commands (`ruff format --check`), the council pre-flight gained a D0 mechanical CI gate that hard-blocks on a red run, and `check_doc_links.py` joined CI — closing the gap that let a format failure ship past an 8-agent council review.
+
 ## [0.28.0] — 2026-07-08
 
 ### Added
@@ -1869,7 +1898,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.28.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/ffroliva/gflow-cli/compare/v0.29.0...v0.30.0
+[0.29.0]: https://github.com/ffroliva/gflow-cli/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/ffroliva/gflow-cli/compare/v0.27.1...v0.28.0
 [0.27.1]: https://github.com/ffroliva/gflow-cli/compare/v0.27.0...v0.27.1
 [0.27.0]: https://github.com/ffroliva/gflow-cli/compare/v0.26.0...v0.27.0

gflow_cli-0.30.0/GEMINI.md

@@ -0,0 +1,37 @@
+# GEMINI.md
+
+> Project memory hub for **Gemini CLI**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Gemini CLI, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Gemini-specific session protocol only.
+
+## What this project is
+
+`gflow-cli` is an unofficial Python CLI that drives [Google Flow](https://labs.google/fx/tools/flow) (Veo image-to-video, Imagen text-to-image) from the terminal by reverse-engineering Flow's private REST API. See [README.md](README.md) for the user-facing overview.
+
+## On every session start
+
+1. Read **[AGENTS.md](AGENTS.md)** — universal rules every agent must follow.
+2. Read **[docs/INDEX.md](docs/INDEX.md)** — routing layer for all project docs and commands.
+3. Pull deeper context on demand (type as plain text in the `agy` TUI prompt):
+   - 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`
+   - Cutting a release → `gflow:release`
+   - Before any commit → `gflow:check`
+
+## Gemini-specific
+
+- Use specialized skills when relevant (e.g., `find-docs` for library research, `pr-council-review` for PR audits).
+- Maintain memory via the `mcp-mempalace` tool if available.
+- Prioritize **turn efficiency** and **high-signal output**.
+
+## Active phase
+
+- **v0.29.0 shipped (2026-07-09):** persistent `gflow instructions` CRUD + movie-manifest instructions brief-sync + six `gflow_instructions_*` MCP tools, with a CI-enforced MCP↔CLI parity contract (`tests/mcp/test_cli_parity.py`) and the agentic-indicator selectors consolidated onto `drivers/factory.py`. Released to PyPI; issue #192 closed.
+- **PR #258 (Camoufox stealth engine, external contribution) — taken over and CLOSED-OUT (2026-07-09).** A 5-persona `/gflow:predict` rejected a rebase in favour of a decomposed, evidence-gated series: Phase 1 landed the MCP video param parity (#273, contributor-credited); a WAF-evidence harness (#274/#275) measured a **0.0% WAF 403 rate over 20 live generations**, so per ADR-13 the Camoufox engine was **NOT built** (#276). The i2i "UUID-ref bug" was investigated and found not-a-bug (#277, stale comment fixed). Contributor thanked + credited on the closed PR. Evidence: `docs/superpowers/spikes/2026-07-09-camoufox-waf-403.md`.
+- **Decoupled Daemon/Worker Plan:** The MCP→FlowWorker wiring shipped in v0.23.0 (PR #228). The remaining headless SSE Daemon + Tauri/React editor blueprint is scheduled in [gflow-studio-scaffold/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-gflow-studio-scaffold/PLAN.md) and [rest-api-layer/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-rest-api-layer/PLAN.md).
+- **Core Lesson (Retrospective):** 
+  - **Verify before adopting — measure, don't assume.** The PR #258 takeover's value was checking every claim against the real code and real data instead of adopting on assertion: a stealth engine we didn't build (0% WAF baseline), a "credit guard" already enforced one layer down, a `display_name` already shipped in v0.26.0, an i2i "bug" that wasn't one, and a concurrency bug that never merged. Five claims, five dismissals — the cheapest correct outcome came from investigation, not implementation.
+  - **ADR gates pay for themselves.** ADR-13 ("confirm the current stealth fix insufficient before implementing an alternative") turned a "build Camoufox" epic into a one-afternoon 20-generation spike that said "don't." Encode the gate as a runnable measurement (`scripts/spike_waf_camoufox.py`), not a debate.
+  - **Decompose contested external PRs; never rebase a branch that's 60+ commits behind.** Cherry-pick/re-express the genuinely-valuable pieces onto fresh branches with `Co-authored-by` credit, evidence-gate the risky parts, and split by concern — one PR per slice.
+  - Kept `gflow-cli` strictly headless (Uvicorn + FastMCP over localhost HTTP/SSE); browser-context locks bypassed by serializing task writes in the SQLite queue with WAL-mode parallel reads. Relational instruction cards must be phrased conversationally (imperative prompts bypass the brief); multi-scene movie sync is read-modify-write to preserve server-assigned card IDs.
+
+See [PLAN.md](PLAN.md) or type `gflow:status` for the current task. Type `gflow:plan <feature>` to create a new feature plan.

{gflow_cli-0.28.0 → gflow_cli-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.28.0
+Version: 0.30.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
@@ -63,7 +63,7 @@ Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
 Provides-Extra: patchright
-Requires-Dist: patchright==1.60.1; extra == 'patchright'
+Requires-Dist: patchright==1.61.2; extra == 'patchright'
 Provides-Extra: s3
 Requires-Dist: s3fs>=2024.2.0; extra == 's3'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 's3'
@@ -147,6 +147,7 @@ Reproduce the recording with [`scripts/record_demo.ps1`](scripts/record_demo.ps1
 | 🎯 **Getting started** | [User Guide](docs/USER_GUIDE.md) · [Usage](docs/USAGE.md) · [Configuration](docs/CONFIGURATION.md) |
 | **Storage & catalog** | [External Storage](docs/EXTERNAL_STORAGE.md) · [Data Layer](docs/DATA_LAYER.md) |
 | 🎭 **Characters** | [Characters](docs/CHARACTER.md), reusable subjects (`gflow character`) |
+| 🤖 **Agentic & automation** | [Instructions](docs/INSTRUCTIONS.md) (`gflow instructions`, persistent brief cards) · [Movie](docs/MOVIE.md) (`gflow movie`, multi-scene manifests) · [Tools](docs/TOOLS.md) (`--tool`, prompt rewriting) · [MCP server](docs/MCP.md) (`gflow mcp run` / `gflow serve`) |
 | 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
 | 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |
 | 📦 **Releases** | [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Release protocol](RELEASE.md) · [Project status](docs/PROJECT_STATUS.md) |
@@ -154,7 +155,7 @@ Reproduce the recording with [`scripts/record_demo.ps1`](scripts/record_demo.ps1
 
 ## For AI agents & LLMs
 
-gflow-cli ships three agent entry points. Pick the one your tool reads first.
+gflow-cli ships four agent entry points. Pick the one your tool reads first.
 
 | File | Audience | Tools |
 |---|---|---|
@@ -185,7 +186,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Project status
 
-**Alpha.** Image (t2i, i2i, upload) and video (t2v, i2v, r2v) run end-to-end on `ui_automation`, with a 5-model Veo picker plus `--duration` and `--count`. Recent additions: `gflow character` for reusable subjects, `gflow scene` for credit-free server-side stitching, and `gflow video chain` for linked clips. Video `batch` is still queued for Phase B, so use a shell for-loop until then ([USAGE](docs/USAGE.md#gflow-video-batch)).
+**Alpha.** Image (t2i, i2i, upload, upscale, batch) and video (t2v, i2v, r2v, batch, chain) run end-to-end on `ui_automation`, with a 5-model Veo picker plus `--duration` and `--count`. Beyond single generations: `gflow movie` renders multi-scene manifests, `gflow instructions` manages persistent Agent-Mode brief cards (credits-free), `gflow character` handles reusable subjects, `gflow scene` does credit-free server-side stitching, `--tool` applies prompt-rewriting tools, and an MCP server (`gflow mcp run` stdio / `gflow serve` HTTP-SSE) exposes the core surface to AI agents with a CI-enforced CLI↔MCP parity contract.
 
 Full milestone history lives in [CHANGELOG.md](CHANGELOG.md). Where the project is heading: [ROADMAP.md](ROADMAP.md).
 

{gflow_cli-0.28.0 → gflow_cli-0.30.0}/PLAN.md

@@ -653,6 +653,8 @@ Records image, batch, T2V, I2V, and R2V provenance in a local SQLite catalog. Re
 
 **Status:** NOT implemented. Parked until the stealth-flag fix (`--disable-blink-features=AutomationControlled` + init script) is confirmed insufficient, or until a contributor picks it up.
 
+**2026-07-09 verification — the current stealth fix is CONFIRMED SUFFICIENT (so this stays parked).** A 20-generation baseline on a live authed profile through the default stealth stack produced a **0.0% WAF 403 rate** (19/20 success; the one miss was a UI-scrape timeout, not a WAF block). This met ADR-13's "must verify before implementing" gate and closed the [Camoufox adoption roadmap](superpowers/plans/2026-07-09-camoufox-adoption/PLAN.md) at Phase 2 — the Camoufox engine was NOT built. Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). Re-run `scripts/spike_waf_camoufox.py` if a repeatable WAF-403 is later observed; a materially non-zero rate would reopen CDP-Attach / Camoufox.
+
 ---
 
 ### Phase 8 — Pluggable storage backend — BACKLOG
@@ -699,7 +701,7 @@ Today the CLI writes media to `$GFLOW_CLI_OUTPUT_DIR` on the local filesystem. P
 | 10 | Both `gflow` and `flow` binary names installed | `flow` is friendlier; `gflow` avoids conflicts with Facebook Flow / MS Power Automate |
 | 11 | LF-only line endings via `.gitattributes` | Single repo source of truth; cross-platform contributors don't think about it |
 | 12 | `Provider` indirection (legacy `providers/`) removed | Superseded by `api.FlowApiClient`. Re-introduce when we add `OfficialVeoProvider` (planned v0.5+) |
-| 13 | CDP attach transport deferred | Must first confirm whether CDP-attached Chrome still sets `navigator.webdriver=true` (which would negate any reCAPTCHA advantage over the current stealth fix). See CDP Attach backlog entry. |
+| 13 | CDP attach / stealth-engine alternatives deferred; **current stealth fix confirmed sufficient 2026-07-09** | Gate met: a 20-gen live baseline through the default stealth stack showed a **0.0% WAF 403 rate**, so the "confirm insufficient before implementing" bar is unmet — CDP-Attach and the Camoufox engine stay parked (Camoufox roadmap closed at Phase 2). Evidence: [superpowers/spikes/2026-07-09-camoufox-waf-403.md](superpowers/spikes/2026-07-09-camoufox-waf-403.md). |
 | 14 | HTTP status path (`get_video_status`) retired alongside `generate_video` | It is the same 401-dead path and would collide with the new `api/video.py:VideoStatus` value object — retiring both together keeps the domain clean. |
 
 ---

{gflow_cli-0.28.0 → gflow_cli-0.30.0}/README.md

@@ -76,6 +76,7 @@ Reproduce the recording with [`scripts/record_demo.ps1`](scripts/record_demo.ps1
 | 🎯 **Getting started** | [User Guide](docs/USER_GUIDE.md) · [Usage](docs/USAGE.md) · [Configuration](docs/CONFIGURATION.md) |
 | **Storage & catalog** | [External Storage](docs/EXTERNAL_STORAGE.md) · [Data Layer](docs/DATA_LAYER.md) |
 | 🎭 **Characters** | [Characters](docs/CHARACTER.md), reusable subjects (`gflow character`) |
+| 🤖 **Agentic & automation** | [Instructions](docs/INSTRUCTIONS.md) (`gflow instructions`, persistent brief cards) · [Movie](docs/MOVIE.md) (`gflow movie`, multi-scene manifests) · [Tools](docs/TOOLS.md) (`--tool`, prompt rewriting) · [MCP server](docs/MCP.md) (`gflow mcp run` / `gflow serve`) |
 | 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
 | 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |
 | 📦 **Releases** | [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Release protocol](RELEASE.md) · [Project status](docs/PROJECT_STATUS.md) |
@@ -83,7 +84,7 @@ Reproduce the recording with [`scripts/record_demo.ps1`](scripts/record_demo.ps1
 
 ## For AI agents & LLMs
 
-gflow-cli ships three agent entry points. Pick the one your tool reads first.
+gflow-cli ships four agent entry points. Pick the one your tool reads first.
 
 | File | Audience | Tools |
 |---|---|---|
@@ -114,7 +115,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Project status
 
-**Alpha.** Image (t2i, i2i, upload) and video (t2v, i2v, r2v) run end-to-end on `ui_automation`, with a 5-model Veo picker plus `--duration` and `--count`. Recent additions: `gflow character` for reusable subjects, `gflow scene` for credit-free server-side stitching, and `gflow video chain` for linked clips. Video `batch` is still queued for Phase B, so use a shell for-loop until then ([USAGE](docs/USAGE.md#gflow-video-batch)).
+**Alpha.** Image (t2i, i2i, upload, upscale, batch) and video (t2v, i2v, r2v, batch, chain) run end-to-end on `ui_automation`, with a 5-model Veo picker plus `--duration` and `--count`. Beyond single generations: `gflow movie` renders multi-scene manifests, `gflow instructions` manages persistent Agent-Mode brief cards (credits-free), `gflow character` handles reusable subjects, `gflow scene` does credit-free server-side stitching, `--tool` applies prompt-rewriting tools, and an MCP server (`gflow mcp run` stdio / `gflow serve` HTTP-SSE) exposes the core surface to AI agents with a CI-enforced CLI↔MCP parity contract.
 
 Full milestone history lives in [CHANGELOG.md](CHANGELOG.md). Where the project is heading: [ROADMAP.md](ROADMAP.md).
 

{gflow_cli-0.28.0 → gflow_cli-0.30.0}/docs/INDEX.md

@@ -38,7 +38,8 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
 | **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
 | **[docs/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/MCP.md](MCP.md)** | MCP server: `gflow mcp run` (stdio) + `gflow serve` (HTTP/SSE), the tools/prompts/resources surface, CLI↔MCP §61 parity, security model, client setup | Configuring an MCP client, working on `gflow_cli.mcp`, or debugging the stdio/SSE transports |
+| **[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` (HTTP/SSE), 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/SSE 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) |
@@ -82,6 +83,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"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)
 **"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 died with exit code 3 (auth) — what now?"** → [USER_GUIDE § Journey 7](USER_GUIDE.md#journey-7--recovering-from-an-authexpirederror-mid-batch)
 **"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)
@@ -120,7 +122,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_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)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_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 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)

gflow_cli-0.30.0/docs/INSTRUCTIONS.md

@@ -0,0 +1,169 @@
+# Agent Instructions — project brief cards for Google Flow's Agent Mode
+
+> **Status.** The ephemeral `-i / --instruction` flag on `gflow image t2i` / `i2i`
+> shipped in **v0.28.0** (live-verified). The persistent `gflow instructions`
+> command group, the `movie.toml` instructions blocks, and the matching
+> `gflow_instructions_*` MCP tools described here shipped in **v0.29.0**
+> (live-verified, credit-free) — this doc now doubles as their spec and reference.
+
+## What an instruction card is
+
+In Google Flow's **Agent Mode**, each project carries a **brief** — a set of
+**instruction cards** the agent consults every time it generates. Each card has:
+
+- a **title** (human label),
+- a **guideline text** (e.g. _"Every image is a flat 2D children's crayon drawing on textured paper"_),
+- zero or more **references** — an attached **image** _or_ a **character** entity,
+- an **enabled** toggle.
+
+Setting up cards is **credits-free** — it's a `PATCH` to the project brief, not a
+generation. Credits are only spent when you actually generate.
+
+### How cards steer generation (mechanism)
+
+Instruction cards apply **only on agentic-cohort sessions**, and only through the
+agent's **reasoning path**: when you make a natural-language request, the agent
+rewrites the image prompt to fold in every **enabled** card (live-verified — an
+enabled "crayon drawing" card turned a style-neutral _"a red bicycle"_ prompt into
+a crayon bicycle; an attached crayon **reference image** did the same). A card
+with `enabled = false` stays in the brief but is ignored. On a classic-cohort
+session, cards do not apply and `gflow` warns.
+
+## The three-layer pipeline
+
+```
+1. SET UP   project context   →  gflow instructions add / apply   (credits-free)
+2. GENERATE using that context →  gflow image t2i / i2i --project <id>
+3. COMPOSE  per-scene context  →  movie.toml [[…instructions.card]]
+```
+
+**Agents: always set up the brief (layer 1) before generating (layer 2).** The
+brief is what makes generations consistent across a project.
+
+## Ephemeral `-i` vs persistent cards
+
+| | `-i "text"` | `gflow instructions` |
+|---|---|---|
+| Scope | one generation | persists on the project brief |
+| Creates | a fresh enabled text-only card each call | managed cards you can toggle/remove/re-sync |
+| References | text only | image **or** character references |
+| Lookup | never — always creates | by **title** (case-insensitive, fail-fast on ambiguity) |
+
+```bash
+# Ephemeral: a one-off enabled text card for this generation only.
+gflow image t2i "a cat on a chair" -i "flat 2D children's crayon drawing"
+```
+
+## `gflow instructions` command surface
+
+Persistent CRUD over a project's brief cards. Cards are selected by **title**
+(case-insensitive, fail-fast on ambiguity) — the ergonomic default — or by the
+stable server **`--id`** for the ambiguous-title / scripting case (`list --json`
+surfaces ids). Mirrors `gflow character` (select by `--name` or `--entity-id`).
+
+```bash
+gflow instructions add   TITLE --text TEXT [--ref REF]... --project ID [--disabled]
+gflow instructions list  --project ID [--json]
+gflow instructions enable  (TITLE | --id ID) --project ID
+gflow instructions disable (TITLE | --id ID) --project ID
+gflow instructions rm      (TITLE | --id ID) --project ID
+gflow instructions apply   FILE  --project ID   # declarative full-sync (TOML/JSON)
+gflow instructions toggle-mode (--on | --off) --project ID
+```
+
+### The generic `--ref` (one attribute for all reference types)
+
+Flow's card reference picker has **All / Images / Characters** tabs — a reference
+is an **image** or a **character**, and both are ultimately a `referenceId`. So
+there is **one** `--ref` option (repeatable), not separate `--ref-image` /
+`--ref-character` flags. `gflow` classifies each value and routes it to the right
+wire field:
+
+| `--ref` value | Resolves to |
+|---|---|
+| local image path (`./hero.png`) | **upload via REST** (`uploadImage`) → media id → `imageReferenceMediaIds` |
+| generated-image UUID | `imageReferenceMediaIds` |
+| character id or name | `characterReferenceEntityNames` |
+
+> **Uploading a new image to an instruction.** Flow's reference picker has an
+> **"Upload media"** button — a card reference can be a brand-new local image, not
+> just an existing project asset. `--ref ./local.png` covers this using the same
+> **REST upload path** as `gflow image upload` (verified: upload → PATCH the card
+> with the returned media id → the image renders as the card's reference). No UI
+> automation of the picker's upload button is required.
+
+```bash
+# A persistent card that anchors style to a reference image AND a character.
+gflow instructions add "Hero look" \
+  --text "Match the reference image's art style; keep the hero on-model" \
+  --ref ./refs/mood.png \
+  --ref hero-character \
+  --project 6b714c4e-...
+```
+
+### `--project` semantics
+
+`gflow instructions` and generation commands take `--project <id>` to target a
+specific project's brief. Generation with `--project` uses that project's **active**
+(enabled) cards. Without `--project`, generation creates a scratch project (so
+persistent cards only make sense with `--project`).
+
+### `apply FILE` — declarative sync
+
+`gflow instructions apply` replaces the project's cards with the file's contents
+(idempotent full-sync), so a brief can live in version control:
+
+```toml
+# brief.toml
+[[card]]
+title   = "Cinematic lighting"
+text    = "Volumetric cinematic light from camera-left"
+ref     = ["./refs/mood.jpg"]
+enabled = true
+
+[[card]]
+title   = "Hero"
+text    = "Keep the hero on-model"
+ref     = ["hero-character"]
+```
+
+## Design notes (state, ids, persistence)
+
+- **The server is the source of truth.** The brief lives in the project's
+  `agentInfo` (read via `flow.projectInitialData`, written via `PATCH agentInfo`).
+  The web UI can edit cards out-of-band, so every `list`/`enable`/`disable`/`rm`
+  reads the cards **live** — gflow never caches card state locally (a cache would
+  silently drift).
+- **Card ids are stable and preserved.** Each card carries a server `id`. Mutating
+  commands are **read-modify-write** — read the current cards, change one, PATCH the
+  set back **keeping every card's existing id** (so `--id` stays valid and
+  `enable`/`disable`/`rm` edit *the same* card rather than replacing it).
+- **The local database records provenance, not state.** When a generation runs with
+  instructions active, the operation record notes which cards/refs were used (like
+  it already records prompt, refs, and `--tool`) — for history/repro only. It is
+  never read to drive `gflow instructions`.
+- **Declarative intent lives in the file.** For `apply brief.toml`, the
+  version-controlled TOML is the durable copy — not the database.
+
+## Typical agent-driven workflow (machine-readable)
+
+1. Discover/choose a project id (`gflow instructions list` needs `--project`; find
+   it in the Flow editor URL `…/project/<id>/…`).
+2. `gflow instructions apply brief.toml --project <id>` — set up the brief (free).
+3. `gflow image t2i "…" --project <id>` — generate using the active cards.
+4. Adjust: `gflow instructions disable "Cinematic lighting" --project <id>`, regenerate.
+5. `movie.toml` per-scene overrides for multi-scene consistency.
+
+**DO NOT** rely on `-i` for anything you want to reuse — it's per-generation.
+**PREFER** title selection; fall back to `--id` (from `list --json`) only when a
+title is ambiguous.
+**DO** set up the brief before generating; cards only apply on agentic sessions.
+
+## See also
+
+- [USAGE.md](USAGE.md) — full command reference.
+- [MOVIE.md](MOVIE.md) — multi-scene movies (`[[…instructions.card]]` blocks).
+- [MCP.md](MCP.md) — the six `gflow_instructions_*` MCP tools mirroring this command group.
+- [LIVE_VERIFICATION_v0.29.0.md](LIVE_VERIFICATION_v0.29.0.md) — live e2e evidence for the
+  CRUD surface (mechanism, H4 image-reference confirmation). The original plan + spike
+  findings were consolidated and removed when the feature shipped (v0.29.0 release prep).

gflow_cli-0.30.0/docs/LIVE_VERIFICATION_v0.29.0.md

@@ -0,0 +1,89 @@
+# Live Verification — v0.29.0
+
+Release date: 2026-07-09. Headline: **persistent `gflow instructions` CRUD + movie-manifest
+instructions + `gflow_instructions_*` MCP parity tools** (PRs #269, #270, #271).
+
+Verification run: 2026-07-09, live Flow against profile `ffroliva` (agentic cohort), Windows,
+`.venv` build of the release tree. **Credit-free:** brief CRUD is a PATCH (no generation);
+the single image generated to mint a fresh project is Imagen (no Veo credits).
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| `instructions add` (text card + `--ref <image-UUID>` card) | `cli_instructions.py` | ✅ Live: both cards on server brief |
+| `instructions list --json` (live server read) | `cli_instructions.py` | ✅ Live: 3 snapshots, stable shape |
+| `instructions enable` / `disable` (title selection) | `cli_instructions.py` | ✅ Live: exit 0, state flips |
+| `instructions toggle-mode --off/--on` (master switch) | `cli_instructions.py` | ✅ Live: exit 0 both directions |
+| `instructions apply` (TOML full-sync, destructive) | `cli_instructions.py` | ✅ Live: brief replaced, `enabled=false` honored |
+| `instructions rm` (read-modify-write, id preserved) | `cli_instructions.py` | ✅ Live: card dropped, sibling id stable |
+| `gflow_instructions_*` MCP tools (6) | `mcp/tools.py` | ✅ Unit tests (13, fake client) — thin adapters over the SAME `get_agent_info`/`patch_agent_info` primitives live-verified above |
+| MCP↔CLI parity contract | `tests/mcp/test_cli_parity.py` | ✅ CI-enforced (45 CLI leaves, all decided) |
+| Agentic-indicator selector consolidation | `drivers/factory.py` | ✅ Symmetry tests + full suite green |
+| Movie `[instructions]` / `[scene.instructions]` brief-sync | `movie_manifest.py` / `cli_movie.py` | ⚠️ Code-path-verified (see below) |
+
+## Live scenario
+
+Fresh project `9d7b750f-b4a8-4c2f-b5b0-a059cbfbae73` minted via one credit-free t2i
+(`"a single red apple on a white table, studio lighting"`, NARWHAL, portrait), producing media
+`886f0d6c-1baa-460c-a2a0-5a5a463f5ae6`. Then the full CRUD sequence (11 commands, each its own
+browser session, all exit 0):
+
+1. `add "Crayon style" --text …` → text card created.
+2. `add "Mood ref" --text … --ref 886f0d6c-…` → **the generated image's UUID attached as
+   `image_media_ids` on the card** (H4 reference path, previously untested live).
+3. `list --json` → both cards present, master `enabled=true`.
+4. `disable "Crayon style"` / 5. `enable "Crayon style"` → title selection round-trip.
+6. `toggle-mode --off` / 7. `toggle-mode --on` → master switch both directions.
+8. `apply brief.toml` → **full-sync replaced** the brief with `Palette rule` (enabled) +
+   `Framing rule` (`enabled = false` from TOML honored on the server).
+9. `list --json` → exactly the 2 applied cards, prior cards gone (destructive sync confirmed).
+10. `rm "Palette rule"` → card removed.
+11. `list --json` → only `Framing rule` remains, **same server id `efbb029c…` as in snapshot 9**
+    — read-modify-write preserves card ids across mutations.
+
+## Evidence ledger (5-layer)
+
+1. **File count:** exactly one image file written (`886f0d6c-…_1.jpg`, 408,791 bytes).
+2. **Magic bytes:** `FF D8 FF E0` (JPEG/JFIF).
+3. **Dimensions:** 768×1376 valid portrait render (PIL-confirmed).
+4. **Structlog invariants:** `ui_driver.bound mode=agentic` on project entry; 11/11 command
+   exits 0; zero `level=error` events across the run; three parseable
+   `"command": "instructions list"` JSON payloads with consistent card shape.
+5. **User-confirmable artifact:** open
+   <https://labs.google/fx/en/tools/flow/project/9d7b750f-b4a8-4c2f-b5b0-a059cbfbae73> —
+   the brief shows exactly one card, **"Framing rule"**, disabled, matching snapshot 11.
+
+## Movie brief-sync — code-path-verified (deliberate, no credits spent)
+
+`movie run`'s per-scene brief sync (`_BriefSyncCache` full-sync) drives the **same**
+`get_agent_info` → build cards → `patch_agent_info` primitives exercised live above (steps 8–9
+are exactly its full-sync semantics). A true end-to-end check requires generating clips (Veo
+credits); the user chose to defer it this cycle. Unit + BDD suites cover the manifest parsing,
+memoization, and re-sync logic.
+
+## Gates
+
+Local: `ruff check` 0 errors · `ruff format --check` clean · `pyright src` 0 errors ·
+hygiene + doc-links clean · full suite 2137 passed. CI on develop merge commits
+`a0ca311`/`0cc1051`/`ee47c00` (PRs #270/#271/#269): tests (3.11/3.12/3.13) + **SonarCloud
+quality gate** all green.
+
+`/gflow:doc-review`: mechanical checks 1–7 PASS (PROJECT_STATUS.md was stale at v0.27.1 —
+updated). Council verdict: **YELLOW across all 3 auditors, zero release-blockers**.
+14 distinct findings; all Tier 1/Tier 2 fixed in the release-prep commit (README/AGENTS/
+llms.txt entry points now surface instructions/movie/MCP; `[scenes.instructions]` key name;
+SKILL.md `--project` required; MCP.md image-tool `instructions` param; AGENTS.md exit-code
+range 3–25; INDEX §61 dead ref; INSTRUCTIONS.md status pinned to v0.29.0 + orphaned plan
+pointer replaced). Tier 3 deferred to backlog (USER_GUIDE instructions journey,
+ARCHITECTURE module inventory refresh, JSON `apply` example). Council reports at
+`tmp/council/0{1,2,3}-*.md` (local-only). Process note: no release spec existed for this
+cycle; the plan was consolidated and removed on ship.
+
+## Known follow-ups (not in this release)
+
+- Movie brief-sync end-to-end with real clip generation (deferred, credits).
+- Movie pipeline MCP tools; `gflow_list_characters` is still a stub (both are reasoned
+  exemptions in `tests/mcp/test_cli_parity.py`).
+- `gflow_generate_video` deliberately has NO `instructions` param — the video pipeline has no
+  instructions support (documented in `docs/MCP.md`); adding it requires video-transport work.