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

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

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.0] — 2026-07-08
+
+### Added
+
+- **Agent instructions (`-i` / `--instruction`) now actually steer generation.** On an
+  agentic-cohort Flow session, `gflow image t2i "…" -i "Every image is a flat 2D crayon
+  drawing"` makes the agent adopt that style (live-verified end-to-end). Instruction cards are
+  synced to the project's Agent brief via `PATCH /v1/projects/{id}/agentInfo`, and the agent
+  folds every **enabled** card into the generation. Cards carry distinct titles and may
+  reference image assets. Persistent CRUD (`gflow instructions`) and movie-manifest wiring are
+  planned follow-ups.
+
+### Fixed
+
+- **Instructions were silently inert (agentic transport).** Two root causes, both found via a
+  live spike: (1) the composer used an imperative `"Generate N images: …"` directive that the
+  agent passes to the image tool verbatim, bypassing the brief — now phrased conversationally
+  so the agent's reasoning step applies the cards; (2) the brief-level master switch
+  `project_brief.enabled` was never set (defaults off on a fresh project → all cards ignored) —
+  now enabled whenever cards are synced. Also fixes a wrong PATCH content-type
+  (`application/json+protobuf` → HTTP 400, silently) and a hardcoded per-card title that
+  collapsed every card to one name.
+- **`-i` no longer no-ops without warning on a classic-cohort session:** a clear warning is now
+  emitted (instructions only apply on agentic sessions).
+
+## [0.27.1] — 2026-07-07
+
+### Fixed
+
+- **Version Wiring in Movie Handoff:** Properly imported and passed `__version__` to `build_handoff()` generator version instead of using a hardcoded stale default (`0.14.0`).
+- **Rich Markup Escaping in CLI Output:** Escaped brackets in `_format_scene_line` plan output (`[t2v]`, `[r2v]`, and `refs=[...]`) so they are not swallowed by Rich console formatting.
+- **MCP Server Stale Version:** Wired FastMCP version to `__version__` dynamically on startup, fixing the stale `0.21.0` version trap.
+- **MCP Agent Guide:** Added `gflow_list_tools` to the list of available tools in the static MCP agent guide resource.
+
+### Added
+
+- **Document Anchors:** Added HTML anchor (`style-configuration-errors`) to `docs/MOVIE.md` for reserved name `"none"` and unknown style variant `ConfigurationError` paths.
+- **Movie Usages Documentation:** Added complete documentation for `gflow movie run` and `gflow movie template` commands to `docs/USAGE.md`.
+
 ## [0.27.0] — 2026-07-07
 
 ### Added
@@ -1830,7 +1869,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.27.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.28.0...HEAD
+[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
 [0.26.0]: https://github.com/ffroliva/gflow-cli/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/ffroliva/gflow-cli/compare/v0.24.0...v0.25.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.27.0
+Version: 0.28.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.27.0 → gflow_cli-0.28.0}/docs/INDEX.md

@@ -120,7 +120,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.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.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.27.0 → gflow_cli-0.28.0}/docs/LIVE_VERIFICATION_v0.27.0.md

@@ -87,7 +87,14 @@ before PR #259; cosmetic; tracked as a follow-up.
 
 ## Post-tag evidence
 
-*(filled after the v0.27.0 tag push / publish)*
+- Signed tag `v0.27.0` pushed 2026-07-07; `Release` workflow green
+  (build-and-publish 37s, digital attestations generated).
+- GitHub Release **v0.27.0** published 2026-07-07T21:16:40Z (not draft).
+- PyPI: `gflow-cli 0.27.0` live — `gflow_cli-0.27.0-py3-none-any.whl` +
+  `gflow_cli-0.27.0.tar.gz` (verified via the PyPI JSON API).
+- Release PR #260 (`chore/release-v0.27.0 → main`) merged with a merge commit
+  after a fully green matrix + SonarCloud gate; branch deleted.
+- `main` back-merged into `develop` (`2909cb6`) — branches aligned.
 
 ## Automated coverage
 

gflow_cli-0.28.0/docs/LIVE_VERIFICATION_v0.27.1.md

@@ -0,0 +1,26 @@
+# Live Verification — v0.27.1
+
+Release date: 2026-07-07. Headline: **v0.27.0 release follow-up fixes and documentation sync** (Issue #239, PR #261).
+
+Verification run: 2026-07-07, local validation gates, Windows, `.venv` build of the release tree. **Deliberately credit-free**: this patch release contains only default parameter wiring, Rich console escaping, MCP guide documentation synchronization, and user documentation. No live Flow REST api/browser automation code paths were changed, so no live generation credits were spent.
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| Wire package version `__version__` as default `version` in `build_handoff()` | `composition.py` | ✅ Unit tests pass (`test_build_handoff_shape_and_schema`) |
+| Escape brackets `\[` in plan output mode and refs | `cli_movie.py` | ✅ Unit tests pass (`test_format_scene_line_escapes_brackets_for_rich`) |
+| Add `gflow_list_tools` to MCP agent guide | `mcp/resources.py` | ✅ MCP guide resource updated |
+| Set `__version__` on FastMCP server on startup | `mcp/server.py` | ✅ MCP tests pass |
+| Add HTML anchors for style configuration errors | `docs/MOVIE.md` | ✅ Document checked via `check_doc_links.py` |
+| Add `gflow movie` subcommands documentation | `docs/USAGE.md` | ✅ USAGE.md updated and link-checked |
+
+## Evidence ledger (Verification Gates)
+
+All local quality gates executed in order as a merge-readiness baseline:
+1. **Hygiene check:** `check_repo_hygiene.py` ran with 0 violations across 505 tracked files.
+2. **Internal links check:** `check_doc_links.py` successfully resolved all internal markdown links across 24 files (including `docs/MOVIE.md` and `docs/USAGE.md`).
+3. **Lint check:** `ruff check src tests` passed with 0 errors.
+4. **Formatting check:** `ruff format --check src tests` verified all files are formatted.
+5. **Type check:** `pyright src` completed with 0 errors and 0 warnings.
+6. **Tests run:** 2056 tests passed, 16 skipped, 55 deselected.

gflow_cli-0.28.0/docs/LIVE_VERIFICATION_v0.28.0.md

@@ -0,0 +1,59 @@
+# Live Verification — v0.28.0
+
+Release date: 2026-07-08. Headline: **Agent instructions (`-i` / `--instruction`) now actually steer agentic image generation** (PR #263).
+
+Verification run: 2026-07-08, live Flow against profile `ffroliva` (agentic cohort), Windows, `.venv` build of the release tree. **Credit-spending:** this release changes the live agentic generation path, so it was exercised end-to-end against real Flow (image generation).
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| Conversational `_compose_directive` (engages the agent's reasoning path) | `api/transports/drivers/agentic.py` | ✅ Live: enabled card applied |
+| Reconcile sets brief master switch `project_brief.enabled=true` + `text/plain` content-type + status-checked | `api/transports/drivers/agentic.py` | ✅ Live: 200, no `patch_failed` |
+| `AgentInstruction.title` / `resolved_title()` + shared `build_agent_brief_cards()` | `api/image.py` | ✅ Unit tests |
+| `patch_agent_info` returns echoed `projectBrief` | `api/client.py` | ✅ Unit tests |
+| Warn when `-i` used on a classic-cohort session | `api/transports/ui_automation.py` | ✅ Unit tests (both cohorts) |
+
+## Live scenario
+
+`tests/e2e/test_live_agentic_instructions.py` (`-m e2e_image`, `GFLOW_CLI_FORCE_AGENT_UI=1`)
+drove the REAL transport: create project → force agent → reconcile PATCH → conversational
+submit → DOM scrape. Prompt was **style-neutral** ("a cat sitting on a wooden chair next to
+a window") with a single **enabled** instruction card: "Every image MUST be rendered as a
+flat 2D children's crayon drawing on textured paper…". Any crayon styling can therefore only
+have come from the card.
+
+## Evidence ledger (5-layer)
+
+1. **File count:** exactly one image file written per generation (`<media_id>.jpg`).
+2. **Magic bytes:** the downloaded file passed the container sniff (`_image_kind` → `jpeg`).
+3. **Shape:** a valid landscape (16:9) render; agentic DOM scrape reports `(0,0)` sentinel
+   dimensions by design (wire dims are Web-Worker-delegated), so shape is confirmed visually.
+4. **Structlog invariants:** `ui_driver.bound mode=agentic` fired (not classic);
+   `agentic_driver.reconcile_instructions.patch` fired; **no**
+   `agentic_driver.reconcile_instructions.patch_failed` (content-type/auth regression guard).
+5. **User-confirmable artifact:** the generated image is an **unmistakable children's crayon
+   drawing** (waxy strokes, textured paper, primary palette) — visually confirmed to match the
+   enabled card, from a prompt containing zero style words. A control generation with the crayon
+   instruction in the *prompt* (not the card) confirmed the model can render crayon, isolating
+   the card (not a model limitation) as the applied factor.
+
+### Negative control (mechanism proof)
+
+- Imperative `"Generate one image: …"` directive + same enabled card → **photorealistic**
+  (brief bypassed). Conversational phrasing → **crayon** (brief applied). This isolated the
+  phrasing fix. A follow-up run isolated the second fix: with cards synced but
+  `project_brief.enabled` unset → photorealistic; with the master switch on → crayon.
+
+## Gates
+
+Local: `ruff check` 0 errors · `ruff format` clean · `pyright src` 0 errors · unit + BDD suites
+green. CI on PR #263: tests (3.11/3.12/3.13) + **SonarCloud quality gate** all green
+(new-code coverage ≥ 80%).
+
+## Known follow-ups (not in this release)
+
+- `gflow instructions` persistent CRUD subcommand.
+- `movie.toml` per-scene instruction wiring.
+- `GFLOW_CLI_FORCE_AGENT_UI` binding is ~50/50 flaky on fresh projects (may bind classic).
+- H4: reference images (`imageReferenceMediaIds`) on cards — untested.

{gflow_cli-0.27.0 → gflow_cli-0.28.0}/docs/MOVIE.md

@@ -101,8 +101,12 @@ Per-scene selection:
 | *(omitted)* | Uses the base `[style]` suffix. |
 | `style_suffix = "sunset light"` | Scene-specific text appended **after** the variant/base suffix. |
 
-`none` is a **reserved name**: defining `[style.variants.none]` is a
-configuration error, so the opt-out keyword can never shadow a real variant.
+<a name="style-configuration-errors"></a>
+### Style Configuration Errors
+
+There are two style configuration errors that will raise a `ConfigurationError`:
+* **Reserved `none` name:** Defining `[style.variants.none]` is a configuration error, so the opt-out keyword can never shadow a real variant.
+* **Unknown variant name:** Specifying a `style_variant` in a scene that does not exist in `[style.variants]` (and is not `"none"`) is a configuration error.
 
 **Composition rule** (deterministic, no LLM):
 

{gflow_cli-0.27.0 → gflow_cli-0.28.0}/docs/PROJECT_STATUS.md

@@ -4,6 +4,12 @@
 
 ## Current release
 
+**v0.27.1 — alpha.** **v0.27.0 release follow-up fixes and documentation sync (#239).** Patch release wiring package version dynamically to `build_handoff()` and `FastMCP` server, escaping brackets in Rich console planning output, updating MCP agent guide, and adding `gflow movie` usage documentation. Verification: [LIVE_VERIFICATION_v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (credit-free baseline verification).
+
+**Develop (unreleased, post-v0.27.1):** *(empty — develop is the staging branch for the next release).*
+
+<details><summary>v0.27.0 — Global [style] block with named variants + prompt-aware resume for gflow movie</summary>
+
 **v0.27.0 — alpha.** **Global `[style]` block with named variants + prompt-aware resume
 for `gflow movie` (#239).** A `movie.toml` can now express a visual style system once —
 `prefix`/`suffix` on `[style]` plus `[style.variants.*]` sub-tables — and select it
@@ -15,7 +21,7 @@ instead of silently skipped, and dry-run marks it `re-run (style changed)`. Carr
 forward v0.26.0 (i2i select-in-place by UUID). Verification:
 [LIVE_VERIFICATION_v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (credit-free CLI ledger).
 
-**Develop (unreleased, post-v0.27.0):** *(empty — develop is the staging branch for the next release).*
+</details>
 
 <details><summary>v0.26.0 — image i2i references a generated image by UUID (select in place)</summary>
 

{gflow_cli-0.27.0 → gflow_cli-0.28.0}/docs/USAGE.md

@@ -1044,6 +1044,84 @@ GFLOW_EXAMPLE_PROFILE=<your-profile> python examples/batch_from_config.py
 
 The bundled `examples/sample_config.json` produces three images at three aspect ratios in `gflow-output/example-batch/`. Copy and edit for your own scenes.
 
+## `gflow movie`
+
+Sequential TOML-described multi-scene AI movie generation. New in v0.14.0.
+
+### `gflow movie template`
+
+Writes a starter `movie.toml` template.
+
+```text
+gflow movie template [OUTPUT] [--force]
+```
+
+* `OUTPUT`: The destination path for the template file (defaults to `./movie.toml`).
+* `--force`: Overwrite the destination file if it already exists.
+
+### `gflow movie run`
+
+Generates individual video clips sequentially from a single TOML manifest file, maintaining crash-recoverable state in a local state JSON file.
+
+```text
+gflow movie run MANIFEST [--out-dir DIR] [--profile NAME] [--continue-on-error|--fail-fast] [--dry-run] [--stitch]
+```
+
+Refer to the complete [Movie Manifests Guide](MOVIE.md) for detailed syntax, character entity creation, and style consistency features.
+
+### Parameters
+
+* `MANIFEST`: Path to your `movie.toml` manifest file (required positional argument).
+* `--out-dir DIR`: Output directory for generated video clips and the handoff file. Defaults to `out/` or `GFLOW_CLI_OUTPUT_DIR`.
+* `--profile NAME`: Specify Google Flow profile to use.
+* `--continue-on-error`: Skip failed scenes and continue generating subsequent scenes (default).
+* `--fail-fast`: Terminate immediately on the first failed scene generation.
+* `--dry-run`: Parse the manifest, estimate credits, and print the generation plan without calling Google Flow.
+* `--stitch`: Run a post-generation preview stitch using ffmpeg to concatenate clips into a single video file.
+
+### Manifest structure (movie.toml)
+
+```toml
+title = "My Cinematic Film"
+project = "Cinematics"
+
+[style]
+look = "3d animation"
+mood = "mysterious"
+negative = "text, watermark"
+prefix = "Cinematic film still, high detail."
+suffix = "Shot on IMAX 70mm, unreal engine 5 render."
+
+[style.variants.warm]
+suffix = "Golden hour light, warm color grading."
+
+[[characters]]
+name = "Stickman"
+identity = "text"
+voice = "alnilam"
+
+[[scenes]]
+id = "scene_01"
+action = "A mysterious stickman walks slowly through a dark forest."
+framing = "wide"
+duration = 5
+characters = ["Stickman"]
+
+[[scenes]]
+id = "scene_02"
+action = "Close up of the stickman looking back in shock."
+framing = "close-up"
+duration = 5
+characters = ["Stickman"]
+style_variant = "warm"
+```
+
+### Outputs
+
+1. **Clip Files:** Individual video files saved under `<out_dir>/scene_<id>.mp4` (or other formats).
+2. **State File:** A `<stem>-state.json` file recording completed operations, seeds, and metadata, allowing a run to resume without wasting credits.
+3. **Handoff Manifest:** A `<stem>-handoff.json` file that projects the run's metadata and clip paths, designed for downstream assemblers.
+
 ## Recipes
 
 ### Burn through a directory of inputs

gflow_cli-0.28.0/docs/superpowers/plans/2026-07-08-agentic-instructions/PLAN.md

@@ -0,0 +1,329 @@
+# API-Driven & Relational Agentic Instructions Implementation Plan
+
+> **For agentic workers:** Run `/gflow:status --feature agentic-instructions` to find the next
+> unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Implement a programmatic, API-driven, and relational instructions management system in the Google Flow Agentic transport, coordinating reference assets across individual generations and multi-scene movies.
+
+**Architecture:** 
+We will shift from DOM-based automation inside Playwright to direct REST API calls using `PATCH /v1/projects/{projectId}/agentInfo`, which is project-scoped and supports relational asset attachments (`imageReferenceMediaIds`). We will expose this relational schema on the image/video DTOs, integrate it with the background worker, add `movie.toml` scene-level mapping, and conclude with a systematic developer skills audit.
+
+**Predict verdict:** GO — confidence 9/10
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| Medium | API signature drift on Google Flow backend | Scope tests to verify response status and keep Playwright DOM fallback logic in place |
+| Low | Invalid media ID attachments | Pre-flight check verifies that any attached `imageReferenceMediaIds` are active in the project's media catalog |
+
+---
+
+## File structure
+
+### New files
+```
+tests/e2e/test_live_agentic_instructions.py
+  Live verification tests for the instructions lifecycle and image generation.
+```
+
+### Modified files
+```
+src/gflow_cli/api/client.py
+  Add patch_agent_info endpoint method.
+src/gflow_cli/api/image.py
+  Extend AgentInstruction and GenerateImageRequest DTOs.
+src/gflow_cli/api/transports/drivers/agentic.py
+  Update configure_image_settings to call patch_agent_info instead of driving DOM.
+src/gflow_cli/movie_manifest.py
+  Integrate scene-specific instructions sync before generating each scene's clips.
+skills/*
+  Audit and synchronize all agent skills with the latest codebase architecture.
+```
+
+---
+
+## Task 1 — Unit Test & Mock Scaffold (test scaffold)
+
+**What:** Create unit test mocks verifying relational instructions serialization and the `patch_agent_info` method wrapper.
+
+**Files:**
+- `tests/api/transports/drivers/test_agentic.py` — Mock testing for driver-API integration.
+- `tests/worker/test_daemon.py` — Verify relational instructions extraction from background queue payload.
+
+**Steps:**
+- [x] Write mock DTO serialization tests for `AgentInstruction` containing `image_media_ids`.
+- [x] Add assertions ensuring the driver correctly calls the `patch_agent_info` client method with structured payloads.
+
+**Tests created (red):**
+- [x] `test_agent_instruction_serialization_with_references`
+- [x] `test_driver_reconcile_dispatches_patch_payload`
+
+---
+
+## Task 2 — BDD Feature & Step Scaffold (test scaffold)
+
+**What:** Write BDD scenarios to verify relational instructions coordination in Cucumber features.
+
+**Files:**
+- `tests/features/video_agent_ui.feature` — Append scenarios for multi-instruction asset mapping.
+- `tests/features/test_video_agent_ui_steps.py` — Implement step definitions simulating the mock server responses.
+
+**Steps:**
+- [x] Write Cucumber scenario for syncing relational instructions.
+- [x] Mock the tRPC and REST responses for project brief updates.
+
+**Tests created (red):**
+- [x] Scenario: "Syncing instructions containing reference image IDs"
+- [x] Scenario: "Toggling active/inactive states of relational cards"
+
+---
+
+## Task 3 — Relational Instructions API Client Implementation (implementation)
+
+**What:** Implement direct `FlowApiClient` methods for patching agent settings.
+
+**Files:**
+- `src/gflow_cli/api/client.py` — Implement `patch_agent_info(project_id, enabled, cards)`.
+- `src/gflow_cli/api/image.py` — Update `AgentInstruction` class attributes.
+
+**Steps:**
+- [x] Add `image_media_ids` and `character_ids` fields to `AgentInstruction`.
+- [x] Implement `patch_agent_info` using the REST route `PATCH /v1/projects/{projectId}/agentInfo`.
+- [x] Support `updateMask` parameters to selectively update `project_brief.enabled` and `project_brief.cards`.
+
+---
+
+## Task 4 — Driver and Worker Integration (integration)
+
+**What:** Update `AgenticFlowUiDriver` and the daemon worker to use the new API client method.
+
+**Files:**
+- `src/gflow_cli/api/transports/drivers/agentic.py` — Call `patch_agent_info` inside `configure_image_settings`.
+- `src/gflow_cli/worker/daemon.py` — Parse relational assets from task queue and forward them.
+
+**Steps:**
+- [x] Modify `configure_image_settings` to bypass DOM loop reconciliation and call the client REST endpoint directly.
+- [x] Refactor background daemon payload builder to support `image_media_ids` mapping.
+
+---
+
+## Task 5 — Live Agentic Image Generation Spike (spike)
+
+**What:** Validate empirically that the REST PATCH → generate round-trip works as expected
+before writing any more production code. Run a real T2I generation on an agentic profile
+with instructions ON vs OFF. Confirm cards influence output and that the `enabled: false`
+soft-disable is respected by the model.
+
+**Files:**
+- `C:\development\github\gflow-agent-browser-spike\instructions_spike.py` — standalone spike script.
+
+**Steps:**
+- [x] Run `scripts/probe-agent-mode.ps1` on an active Flow browser session to inspect and verify all Agent Mode and sidebar DOM selectors, attributes, and roles.
+- [x] Write spike: create project, PATCH two cards (one enabled, one disabled), generate one image, inspect output. (`scratch/spike_instructions_phase_a.py` + live Chrome; project `6b714c4e…`.)
+- [x] Confirm `enabled: false` card does NOT appear to influence generation. (Confirmed — disabled noir card never injected.)
+- [ ] ~~Confirm `imageReferenceMediaIds` on a card actually anchors the model's visual style.~~ Deferred — not tested; plausible via the reasoning path. Probe later with an uploaded asset.
+- [x] Document findings in `spike-findings.md` (pass/fail per hypothesis).
+- [ ] **Spike Fallback:** If reference media IDs are ignored, specify the fallback to degrade gracefully (using them only for UI catalog context, with warning logged).
+
+**Gate:** ✅ MET (with redesign requirement). All hypotheses have observed answers.
+
+**Spike outcome (2026-07-08):** Cards DO steer output (H1/H2/H3 confirmed) **but only
+through the agent's reasoning path.** An imperative `"Generate N image(s): {prompt}"`
+directive is passed to the image tool verbatim → brief ignored; a conversational
+request → agent rewrites the tool prompt and injects enabled cards. **Load-bearing
+consequence:** the transport made instructions inert on the CLI for TWO reasons
+(both found live via the e2e; both fixed in this branch):
+- `_compose_directive` used the imperative form → now conversational (`"Make me a picture of {prompt} …"`).
+- `_reconcile_instructions` never set the brief-level **master switch**
+  `project_brief.enabled` (defaults OFF on a fresh project → all cards ignored) → now
+  PATCHes `updateMask=project_brief.enabled,project_brief.cards` with `enabled:true`.
+- `_reconcile_instructions` content-type `application/json+protobuf` (silent 400)
+  → `text/plain`; response status now checked/warned.
+- Per-card `title` hardcode → `AgentInstruction.title` + `resolved_title()`, via a
+  shared `build_agent_brief_cards()` used by both PATCH paths.
+- `patch_agent_info` now returns the echoed `projectBrief` (no `GET /agentInfo`; it 404s).
+
+**Live e2e (Task 9, done early):** `tests/e2e/test_live_agentic_instructions.py`
+(`-m e2e_image`, `GFLOW_CLI_FORCE_AGENT_UI=1`) drives the real transport and was run
+to a **verified crayon drawing** from a style-neutral prompt — cards steer output
+end-to-end. Known follow-up: `GFLOW_CLI_FORCE_AGENT_UI` binding is ~50/50 flaky (may
+bind classic and silently skip instructions). See `spike-findings.md`.
+
+---
+
+## Task 6 — `gflow instructions` Docs-First Spec (docs-first)
+
+**What:** Write all user-facing documentation BEFORE implementing the subcommand.
+The docs become the acceptance criteria for Task 7. This forces the design to be
+coherent and agent-readable before a single implementation line is written.
+
+**Design decisions locked in (do not reopen without a predict):**
+- `-i "text"` on generation commands = ephemeral text-only card, always creates, never looks up.
+- `gflow instructions` = persistent CRUD on project-scoped cards, supports refs and characters.
+- No UUID inputs at the CLI; title matching is case-insensitive, fail-fast on ambiguity.
+- `--project proj-id` on generation commands selects which project's active cards to use.
+- Cards with `enabled: false` stay in the project but are ignored by the model.
+
+**Files:**
+- `docs/INSTRUCTIONS.md` — full user-facing guide: what instruction cards are, the
+  three-layer pipeline (setup → generate → compose), examples, movie context.
+- `skills/gflow-cli/SKILL.md` — add a **Pipeline** section documenting the layered
+  sequence so AI agents always call setup before generation.
+- `docs/USAGE.md` — add `gflow instructions` to the command surface section.
+- `docs/INDEX.md` — register the new `INSTRUCTIONS.md` documentation file.
+- `docs/superpowers/plans/2026-07-08-agentic-instructions/PLAN.md` — update this file
+  (Task 5b spec section).
+
+**Steps:**
+- [ ] Write `docs/INSTRUCTIONS.md` covering:
+  - What an instruction card is and why it is credits-free to set up.
+  - The three-layer pipeline: project context → generation → movie composition.
+  - Full `gflow instructions` command surface with annotated examples.
+  - Ephemeral `-i` vs persistent card distinction.
+  - `--project` flag semantics for generation commands.
+  - Typical agent-driven workflow (numbered steps, machine-readable).
+- [ ] Update `skills/gflow-cli/SKILL.md` — add Pipeline section (with explicit project ID discovery guidance and "DO NOT" rules).
+- [ ] Update `docs/USAGE.md` — add `gflow instructions` command surface entry.
+- [ ] Update `docs/INDEX.md` — register link to `docs/INSTRUCTIONS.md`.
+- [ ] Run `scripts/ci/check_doc_links.py` — all internal links must resolve.
+
+**Gate:** Docs reviewed and approved before any Task 7 implementation starts.
+
+---
+
+## Task 7 — `gflow instructions` Subcommand Implementation (implementation)
+
+**What:** Implement the `gflow instructions` Click subcommand group based on the
+Task 6 spec. Strictly no scope creep — implement exactly what the docs say.
+
+**Files:**
+- `src/gflow_cli/cli_instructions.py` — new module with Click group + subcommands.
+- `src/gflow_cli/cli.py` — register `gflow instructions` group.
+- `src/gflow_cli/api/client.py` — add `get_agent_info()` for list/enable/disable lookups.
+- `src/gflow_cli/cli_image.py` / `src/gflow_cli/cli_video.py` — add `--project` option.
+- `tests/test_cli_instructions.py` — unit tests for all subcommands.
+- `tests/features/instructions.feature` — BDD feature definitions for subcommands.
+- `tests/features/test_instructions_steps.py` — BDD step definitions.
+
+**Subcommands:**
+```
+gflow instructions add TITLE --text TEXT [--ref PATH]... [--character ID]... [--project ID]
+gflow instructions list [--project ID] [--json]
+gflow instructions enable TITLE [--project ID]
+gflow instructions disable TITLE [--project ID]
+gflow instructions rm TITLE [--project ID]
+gflow instructions apply FILE [--project ID]   # declarative full-sync from TOML/JSON
+gflow instructions toggle-mode [--on/--off] [--project ID] # toggle project-level Agentic mode
+```
+
+**Steps:**
+- [ ] Implement `get_agent_info(project_id)` client method returning a typed DTO (`ProjectBrief`).
+- [ ] Implement `gflow instructions add` (upload refs → get media UUIDs → PATCH cards).
+- [ ] Implement `gflow instructions list` with Rich table output and `--json` flag.
+- [ ] Implement `gflow instructions enable` / `disable` (title match, case-insensitive, fail-fast).
+- [ ] Implement `gflow instructions rm` (remove matching card, PATCH remaining).
+- [ ] Implement `gflow instructions apply FILE` (declarative full-replace idempotent sync from TOML/JSON manifest).
+- [ ] Implement `gflow instructions toggle-mode` (programmatic toggle of project-level Agentic mode).
+- [ ] Add `--project proj-id` to `gflow image t2i` / `i2i` / `gflow video` commands.
+- [ ] Gracefully handle classic UI projects in `gflow instructions` — fail-fast with clean HTTP error reporting.
+- [ ] **UI Visual Consistency:** Ensure the driver's `configure_image_settings` clicks the `article_spark` button if the agent sidebar is closed, ensuring the browser Page visually reflects active cards.
+- [ ] Ensure MCP schema symmetry: mirror all subcommands in MCP tool definitions (CI gate).
+- [ ] Create `tests/features/instructions.feature` and verify CLI subcommands via BDD tests.
+- [ ] All new commands covered by unit tests.
+- [ ] Run `/gflow:check` — all gates green.
+
+---
+
+## Task 8 — Movie Manifest Integration (movie)
+
+**What:** Integrate instruction card management into `gflow movie` so each scene can
+declare its own instruction context declaratively in `movie.toml`.
+
+**Files:**
+- `src/gflow_cli/movie_manifest.py` — parse `[instructions]` and `[[scene.instructions]]` blocks.
+- `src/gflow_cli/cli_movie.py` — inject `gflow instructions apply` step before each scene's generation.
+- `docs/MOVIE.md` — document the `instructions` blocks in the manifest format.
+
+**Steps:**
+- [ ] Define `movie.toml` schema for global + per-scene instruction blocks:
+  ```toml
+  [instructions]
+  # Applied to all scenes unless overridden.
+  [[instructions.card]]
+  title = "Cinematic Lighting"
+  text  = "Volumetric cinematic light from camera-left"
+  ref   = "./refs/mood.jpg"
+  enabled = true
+
+  [[scene]]
+  prompt = "hero emerges from fog"
+  [scene.instructions]
+  disable = ["Cinematic Lighting"]
+  [[scene.instructions.card]]
+  title = "Fog Atmosphere"
+  text  = "Dense volumetric fog, low contrast"
+  ```
+- [ ] Implement manifest parser for the new blocks.
+- [ ] Inject a pre-generation `PATCH agentInfo` call for each scene's instruction diff.
+- [ ] Update `docs/MOVIE.md` with the new schema.
+- [ ] BDD scenario: multi-scene movie with per-scene instruction override.
+
+---
+
+## Task 9 — E2E Verification (e2e)
+
+**What:** Live integration test covering the full instructions lifecycle and a real
+generation using the established context.
+
+**Files:**
+- `tests/e2e/test_live_agentic_instructions.py` — full create-patch-generate-teardown lifecycle.
+
+**Steps:**
+- [ ] Write `test_live_agentic_instructions.py`:
+  - Create a project.
+  - Add two instruction cards (one with a reference image).
+  - Enable one, disable the other.
+  - Generate one image (`gflow image t2i`).
+  - Assert generation succeeds and returns a valid `GeneratedImage`.
+  - Teardown: delete cards.
+- [ ] Mark test `@pytest.mark.live` and `@pytest.mark.e2e`.
+- [ ] Document run instructions in `docs/TESTING.md`.
+
+---
+
+## Task 10 — Re-assess and Optimize Developer Skills (skills audit)
+
+**What:** Systematically review and update all agent skills to reflect the full
+evolved architecture including the new instruction pipeline, `gflow instructions`
+subcommand, and layered project context model.
+
+**Files:**
+- `skills/gflow-cli/SKILL.md` — primary update (Pipeline section added in Task 6).
+- `skills/predict/SKILL.md`, `skills/scenario/SKILL.md`, `skills/plan/SKILL.md`,
+  `skills/status/SKILL.md`, `skills/pr-council-review/SKILL.md` — audit each.
+
+**Steps:**
+- [ ] Scan all skills and compare against current codebase: commands, transports, APIs, DTOs.
+- [ ] Identify stale: legacy DOM transport descriptions, missing `gflow instructions`, old REST routes.
+- [ ] Update each skill to correctly describe current components (SQLite ledger, daemon workers,
+  REST API, new `gflow instructions` subcommand, layered pipeline model).
+- [ ] Verify all YAML frontmatter, internal links, and cross-references resolve correctly.
+- [ ] Run `scripts/ci/check_doc_links.py` — merge gate.
+
+---
+
+## Definition of done
+
+- [ ] All task steps checked off
+- [ ] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated
+- [ ] `docs/INSTRUCTIONS.md` created and registered in `docs/INDEX.md`
+- [ ] `skills/gflow-cli/SKILL.md` Pipeline section present
+- [ ] `docs/USAGE.md` covers `gflow instructions` command surface
+- [ ] `docs/MOVIE.md` documents `[instructions]` manifest blocks
+- [ ] BDD feature files cover all scenarios (including CLI subcommands in `tests/features/instructions.feature`)
+- [ ] MCP schema symmetry test passes (CI gate)
+- [ ] Live spike findings documented in `spike-findings.md`
+- [ ] Documented link check (`scripts/ci/check_doc_links.py`) passes without errors
+- [ ] No `# TODO` in diff without a tracked issue link
+