gflow-cli 0.13.0__tar.gz → 0.15.0__tar.gz

{gflow_cli-0.13.0 → gflow_cli-0.15.0}/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] — 2026-06-09
+
+### Added
+
+- **`gflow image` can reference locked CHARACTER entities** for character-consistent
+  stills. New `--reference-entity <id>` (repeatable) + `--reference-entity-name` on
+  `image t2i` / `i2i`, plus `--project <id>` to generate in an EXISTING project (where
+  the entities live) instead of a throwaway scratch project. Entities attach through
+  the editor's **Personagens picker** and ride the submit as `referenceEntities`
+  (confirmed against the live API); `_build_batch_generate_images_body` serializes them
+  so non-UI/headless transports get parity too. Entities count toward the per-model
+  reference cap. `--project` / `--reference-entity` are single-prompt only; for a pure
+  character reference use `t2i` (`i2i` still needs a `--ref`). See `docs/USAGE.md` →
+  "Character-consistent images (entity references)".
+
+### Fixed
+
+- `--project` no longer overwrites an existing project's stored title/source in the
+  local history DB (the recorder preserves the curated title for non-created projects).
+
+### Security
+
+- `--project` / `--reference-entity` ids are validated at the CLI boundary
+  (`[A-Za-z0-9-]{1,128}`), closing an unvalidated `page.goto` navigation path
+  (`project_editor_url` lacked the allowlist its sibling routes enforce) and a
+  CSS-selector injection vector (`data-tile-id='fe_id_<id>'`). The request-body debug
+  logger elides large reference-field values so Flow-built image bytes can't leak into
+  logs.
+
+### Internal
+
+- Bump dev/CI `ruff` to `0.15.16` (both the `dev` extra and the `dependency-groups`
+  pin; supersedes Dependabot PR #165, which updated only the soft `>=` extra and not
+  the hard `==` group pin CI actually uses). `ruff check` / `format --check` clean.
+
+## [0.14.0] — 2026-06-07
+
+### Added
+
+- **`gflow movie` — multi-scene, character-consistent video generation.** A TOML
+  manifest (`gflow movie template` / `gflow movie run`) drives a sequence of clips
+  that reuse a single Flow CHARACTER entity (reference-to-video) so the same face
+  and voice carry across every scene. Generate-only by default; `--stitch`
+  produces an ffmpeg preview concat; runs are crash-resumable via the sibling
+  `<manifest>-state.json`; a versioned handoff manifest is written for downstream
+  composition (e.g. Remotion). Deterministic prompt assembly (`composition.py`),
+  scene = clip.
+- **`docs/MOVIE.md`** — manifest format, the run lifecycle (the headed browser is
+  required through generate → poll → download), the character-entity attach
+  mechanism, and the best-effort consistency model.
+- Dev utilities: `scripts/dev/make_project.py` (create a Flow project) and
+  `scripts/dev/patch_character.py` (rename / set voice + personality on an entity).
+
+### Fixed
+
+- **R2V character reuse now actually rides the wire.** The entity is attached via
+  the resource picker's **Personagens tab → right-click → "Incluir no comando"**
+  (which stages `referenceEntities`; a left-click on the Tudo tile only stages the
+  thumbnail as a `referenceImage`). The submit backstop now reads the response's
+  real `media[].mediaMetadata.requestData.videoGenerationRequestData.videoGenerationEntityInputs`
+  path instead of the request-shape `requests[].referenceEntities` — which had
+  false-rejected every successful entity generation. `omni-flash` R2V verified to
+  carry the entity.
+- Cleared pre-existing type/test debt: `pyright src` is clean again (the missing
+  `project_id` parameter was added to the `VideoCapableTransport` protocol and the
+  `_enter_editor` type stub); regenerated `uv.lock` (jsonschema dev dependency).
+
 ## [0.13.0] — 2026-06-04
 
 ### Added
@@ -1402,7 +1469,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.13.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/ffroliva/gflow-cli/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/ffroliva/gflow-cli/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/ffroliva/gflow-cli/compare/v0.10.0...v0.11.0

{gflow_cli-0.13.0 → gflow_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.13.0
+Version: 0.15.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
@@ -53,7 +53,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.15.15; extra == 'dev'
+Requires-Dist: ruff>=0.15.16; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'

gflow_cli-0.15.0/PR162_MOVIE_CHARACTER_REVIEW.md

@@ -0,0 +1,137 @@
+# PR #162 Review — Movie Orchestration Character Consistency
+
+**Branch:** `pr162` · **Scope:** `gflow movie` orchestrator (`cli_movie.py`, `movie_manifest.py`) + video transport
+**Verdict:** Sound foundation, correct project consolidation, but the headline goal (consistent character) is **not achievable with the current r2v-by-uploaded-image approach** — and there is a **release-blocking `NameError` that aborts every multi-scene run after scene 1.**
+
+---
+
+## TL;DR
+
+| # | Objective | Finding |
+|---|-----------|---------|
+| 0 | *(not in brief)* | 🔴 **CRITICAL** — `asyncio.sleep(5)` at `cli_movie.py:344` with **no `import asyncio`** → `NameError` on the 2nd scene of every movie, outside the try/except → whole run aborts after 1 scene. |
+| 1 | Native character integration | ✅ **Feasible & protocol-ready.** Flow's wire has a native field `referenceEntities:[{entityId}]` on `video:batchAsyncGenerateVideoReferenceImages` (live-verified, `docs/CHARACTER.md §6.6/§8`). The entity_id is *already saved* in state but never used. Needs a new transport path (composer resource-picker → "Personagens") + DTO field. |
+| 2 | r2v vs i2v / chain | ✅ The chaining engine **already exists** (`chain.py`, `media.extract_last_frame`, `gflow video chain`). It's just not wired into `movie.toml`. r2v+entity = identity; i2v-chain = motion continuity; **mutually exclusive per generation** (DTO enforces frames XOR references). |
+| 3 | Project consolidation | ✅ **Correct and it's the enabler.** `manifest.project` is threaded to character-create *and* every scene; `_enter_editor` deep-links to that project. This is exactly the precondition that makes native `referenceEntities` selection possible. |
+| 4 | Error handling (`generate_resp`/403) | ✅ **Already fixed.** `generate_resp={}` bound before `try` (`:1421`); 403→`WafRejectionError`, silent→`TimeoutError`; listeners freed in `finally`. No UnboundLocal remains. |
+
+---
+
+## 0. 🔴 CRITICAL — `asyncio` is not imported (multi-scene runs crash)
+
+`cli_movie.py:342-345`:
+
+```python
+# reCAPTCHA cooldown
+if completed_scene_ids:
+    await asyncio.sleep(5)      # NameError: name 'asyncio' is not defined
+```
+
+- `asyncio` appears **exactly once** in the file (the usage); it is **not** in the import block (`:17-44`).
+- `completed_scene_ids` is non-empty from the 2nd scene onward (appended at `:373`, and on resume at `:332`).
+- The call sits **outside** the per-scene `try/except` (`try` starts at `:346`), so the `NameError` propagates out of `_run_movie` → caught by `run_with_handlers` → **the entire movie aborts after exactly one scene**, regardless of `--continue-on-error`.
+- On *resume* it's worse: the first already-completed scene appends to `completed_scene_ids`, so the very first new scene hits the cooldown and crashes → **resume can make zero forward progress.**
+
+**Why it escaped CI:** the only async-orchestrator test (`tests/cli/test_cli_movie.py:368 test_happy_path_no_characters`) uses a **single** scene. No test drives `_run_movie` with ≥2 scenes, so the cooldown branch is never executed. (The `out/stickman-v3/` artifacts predate this regression — file mtime is later than the renders.)
+
+**Fix (one line):** add `import asyncio` to the import block. **Then add a 2-scene orchestrator test** so this can't regress (see §6).
+
+---
+
+## 1. Native character integration — the real fix for divergence
+
+### Current behaviour (confirms the brief)
+- `character_create` downloads face/body to **local disk**; `CharacterState` stores both `entity_id` *and* `image_paths` (`cli_movie.py:454-457`).
+- `_collect_refs` (`cli_movie.py:470-483`) returns **only `image_paths`** for r2v. `entity_id` is captured and then ignored.
+- `_generate_scene` passes those local paths as `reference_images`; the transport's `_attach_references` (`ui_automation_video.py:1092`) **re-uploads each file** via the "Add Media" dialog → fresh media IDs every scene → Flow sees unrelated assets → the Stickman drifts. **Exactly the diagnosed flaw.**
+
+### The native path exists and is verified
+From `docs/CHARACTER.md §6.6` (live-verified 2026-06-02, `labs.google23.har`):
+
+```json
+"video:batchAsyncGenerateVideoReferenceImages" → {
+  "referenceImages":   [ { "mediaId", "imageUsageType":"IMAGE_USAGE_TYPE_ASSET" } ],
+  "referenceEntities": [ { "entityId" } ]      // ← native character identity
+}
+```
+
+- `referenceEntities` is a **list** → multi-character per scene (`VIDEO_MODEL_CAPABILITY_MULTI_REFERENCE`).
+- UI flow: composer → resource picker (*"Pesquisar recursos"*) → **Personagens** tab → select → **"Incluir no comando"** → injects `referenceEntities`.
+- CLI `gflow video … --character <id>` is documented **backlog Phase 3 — unimplemented** (`docs/CHARACTER.md §8`). So this is *new automation*, not a refactor of existing code.
+
+### Proposed refactor
+
+**(a) DTO** — `api/video.py`, `GenerateVideoRequest`:
+```python
+reference_entities: tuple[str, ...] = ()   # R2V — Flow CHARACTER entity ids
+```
+⚠️ Relax `__post_init__`: today R2V **requires** `reference_images` (`video.py:249-252`). Change to *require `reference_images` **or** `reference_entities`* (either anchors the clip). Keep frames XOR references.
+
+**(b) Transport** — new `_attach_character_entities(page, names, out_dir)` that, in `references` sub-mode, opens the resource picker, switches to the Characters/"Personagens" tab, selects each character **by display name**, clicks "Include in prompt". In `_generate_video_locked` R2V branch (`:1406`): if `request.reference_entities` → use entity attach; else fall back to `_attach_references`. (Both *may* coexist per the wire.)
+- **Defense-in-depth (mirror the #125 backstop):** after submit, assert the captured generate payload's `referenceEntities` contains the expected `entityId`; if it's missing, raise rather than report a false success — otherwise an entity that silently failed to attach degrades to a plain text-only clip with no warning.
+
+**(c) Orchestrator** — `_collect_refs` → return entity refs when `CharacterState.entity_id` is present, image paths only as fallback. Pass `reference_entities=(...entity_ids...)` into `GenerateVideoRequest`. Selection is **by name** (what the picker shows); `entity_id` is the verification key. No `movie.toml` change needed — `characters = ["Stickman"]` already names them; the orchestrator maps name→entity_id from state.
+
+**(d) Pre-flight guard** — before the scene loop, verify each named entity actually exists in the project (`client.get_character(entity_id=...)`). Currently `_collect_refs` silently **drops** a missing character (`log.warning` + `continue`, `:478`) → the scene generates with **no refs at all** → guaranteed divergence with no hard failure. Fail loud instead.
+
+---
+
+## 2. r2v vs i2v for journey continuity — the chain engine already exists
+
+**Key constraint:** R2V "references" and I2V "frames" are **separate, mutually-exclusive composer sub-modes** (`_switch_video_sub_mode`, `:903`) and the DTO enforces it (`video.py:245-252`). You **cannot** have character-entity identity *and* a seeded start-frame in the *same* generation.
+
+What each buys you:
+- **r2v + `referenceEntities`** → strong **identity** consistency per clip; hard cuts between scenes.
+- **i2v chain** (scene N+1 start = scene N's last frame) → **motion/visual continuity**; but link 0 has no identity anchor and identity drifts frame-to-frame.
+
+**You already have the chain machinery** — it's just not exposed in `movie.toml`:
+- `media.extract_last_frame(src, dst, *, offset_ms=0)` (`media.py:31`)
+- `chain.run_chain(...)` + `ChainLinkSpec`/`ChainLinkResult`/`FrameExtractor` protocols (`chain.py:74-185`) — record-before-extract, crash-resumable.
+- `chain_repo.ChainLinkRecorder` + migration `0005_add_chain_links.sql`.
+- `gflow video chain` (`cli_video.py:324 _run_chain`): "link 0 as T2V, every later link as I2V seeded by the previous clip's last frame."
+
+**Recommendation:** add an opt-in chain mode to `movie.toml` that routes through the existing `chain.run_chain()` rather than reimplementing it (e.g. top-level `mode = "chain"`, or scene-level `chain_from = "<previous scene title>"`). Then give honest guidance in docs:
+
+> For a **journey where the character must stay the same**, prefer **r2v + native character** on *every* scene (each clip independently anchored to the entity → best identity, accepts cuts). Use **chain** when smooth motion handoff matters more than identity, accepting drift. They can be mixed per-scene but never combined within one clip.
+
+The strongest practical journey today = r2v+entity on each scene; chaining is complementary, not a substitute, for the *consistency* goal specifically.
+
+---
+
+## 3. Project consolidation — verified, and it's load-bearing
+
+`manifest.project` (single value) is passed to `_create_character(project_id=…)` (`:309`) **and** `_generate_scene(project_id=…)` (`:356`); `_enter_editor` deep-links via `routes.project_editor_url(locale, project_id)` → `page.goto` (`ui_automation.py:815-818`); characters are created at the project's character-editor URL (`:2275`). So every character and every scene live in **one** project. ✅
+
+This is precisely why the native-character refactor (§1) works: the entity must be in the **active** project to appear in the composer's "Personagens" picker. The consolidation you added is the enabler — keep it, and add the §1(d) guard so a missing entity fails loudly instead of silently degrading.
+
+---
+
+## 4. Error handling (`generate_resp` / `responses` / 403) — already correct
+
+- `generate_resp: dict[str, Any] = {}` is bound **before** the `try` (`ui_automation_video.py:1421`) → no access-before-assignment on any failure path.
+- `_await_generate_response` raises a clear `TimeoutError` when reCAPTCHA fails *silently* (no response captured, `:1172-1179`).
+- `_parse_generate_response` maps **401→`AuthExpiredError`**, **403→`WafRejectionError`**, other non-200→`WireFormatError` (`:1245-1262`).
+- Both response listeners are removed in `finally` (`:1484-1488`); `generate_handler`/`status_handler` are bound before the `try`.
+- `responses` only appears in comments — no live variable by that name. **No remaining UnboundLocal/TypeError on the 403 path.** Nothing to fix here.
+
+---
+
+## 5. Other observations (non-blocking)
+
+- **Dry-run vs reality mismatch:** the plan prints `refs=[<names>]` (`:260`) but r2v actually consumes image *paths*; after §1 this becomes accurate again (names = entities). Minor.
+- `CharacterState`/`SceneState` are non-frozen dataclasses — intentional (mutated in place); fine.
+- Summary stitch hint uses `flow_operation_id or media_id` (`:371`) — good.
+
+## 6. Testing gap (ties to the DoD: "full e2e covering all scenarios")
+
+- No test drives `_run_movie` with **≥2 scenes** → the cooldown/`asyncio` path and the resume-append path are unexercised. Add: a 2-scene happy path (mock `_generate_scene`) that would have caught §0, and a resume test (one scene pre-completed in state).
+- Add a unit test asserting `_collect_refs` (post-refactor) returns entity ids when present, and a transport test asserting `referenceEntities` lands in the captured payload.
+- Per project DoD memory, a movie feature isn't done until a live e2e covers happy + all error/exit paths on a real project.
+
+---
+
+## Suggested sequencing
+
+1. **Hotfix now:** `import asyncio` + 2-scene orchestrator test. (Unblocks the feature as-is, even with uploaded-image refs.)
+2. **Identity fix:** DTO `reference_entities` + validation relax + transport entity-attach + payload backstop + orchestrator wiring + missing-entity guard.
+3. **Journey mode (opt-in):** wire `movie.toml` → existing `chain.run_chain()`; document the identity-vs-continuity tradeoff.

{gflow_cli-0.13.0 → gflow_cli-0.15.0}/docs/INDEX.md

@@ -33,6 +33,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/SECURITY.md](SECURITY.md)** | What secrets are stored where, threat model, hardening | Audit, code review, multi-user machines |
 | **[docs/DATA_LAYER.md](DATA_LAYER.md)** | Local SQLite catalog: goals, schema, recording flow, redaction, `gflow data` CLI, migrations, extension guide | Anything touching `gflow_cli.data`, debugging missing rows, building I2V/repair tooling, auditing what is stored |
 | **[docs/CHARACTER.md](CHARACTER.md)** | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via `referenceEntities` (#145) | Working on `gflow character`, reusing a character in generations, or understanding Flow's character wire protocol |
+| **[docs/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 |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Gemini CLI, Aider, etc. | Any agent wanting to use gflow-cli correctly |
 | **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |

gflow_cli-0.15.0/docs/MOVIE.md

@@ -0,0 +1,141 @@
+# Movie — multi-scene, character-consistent films
+
+`gflow movie` turns a single TOML manifest into a sequence of generated video
+clips that share the **same characters** (face + voice) across every scene. It
+is the orchestration layer on top of `gflow character` (entity creation) and
+`gflow video` (R2V generation).
+
+> Status: under active development on the movie feature branch. The wire
+> protocol and CLI surface below are live-verified but may still change before
+> release.
+
+## Quick start
+
+```bash
+# 1. Scaffold a manifest
+gflow movie template movie.toml
+
+# 2. Edit movie.toml (characters + scenes), then run
+gflow movie run movie.toml --profile <chrome-profile>
+```
+
+`movie run` is **generate-only** by default: each scene becomes its own clip in
+the output directory. Pass `--stitch` for an optional ffmpeg hard-concat preview
+(no transitions — not a deliverable).
+
+## Manifest (`movie.toml`)
+
+```toml
+schema_version = 1
+title = "E2E Stickman"
+project = "6ba50219-…"            # reusable Flow project id
+output_dir = "./out"
+
+[[characters]]
+name = "Stickman"
+identity = "entity"               # reuse a Flow CHARACTER entity across scenes
+face_prompt = "Simple round stickman, black ink lines, smiley face"
+voice = "alnilam"                 # voice baked into the entity at creation
+
+[[scenes]]
+id = "summit"                     # stable key — used for resume
+action = "stands on a clifftop at sunset, waves at the camera"
+framing = "wide"
+characters = ["Stickman"]         # which characters appear (drives R2V reuse)
+speaker = "Stickman"
+line = "We finally made it to the top!"
+aspect = "9:16"
+model = "veo-lite"
+duration = 8
+```
+
+On first run, characters with `identity = "entity"` are created once (image
+generation — **free**, no credits) and cached. Each scene then generates a clip
+that **reuses the same Flow CHARACTER entity** so the character drives every
+scene from one identity.
+
+> **Consistency is best-effort, not pixel-exact.** gflow guarantees the *right
+> entity rides the wire* (`consistency_method = entity`); the final on-screen
+> fidelity is Flow's Veo R2V model, which may reinterpret minimalist or
+> hand-drawn references (e.g. a single round body can render as stacked
+> circles). For tighter results, use clearer/richer reference images and a
+> higher-tier model (`veo-quality`/`veo-fast` rather than `veo-lite`) — the same
+> trade-offs you would hit driving Flow's UI by hand.
+
+## Run lifecycle — keep the browser open
+
+`gflow movie run` drives the **real Flow web UI** in a headed Chrome window
+(your `--browser chrome` profile). For **each scene** the same browser window
+is used end-to-end:
+
+1. **Attach** the character entity to the generation (see below).
+2. **Submit** the prompt — this passes reCAPTCHA and **spends 1 video credit**.
+3. **Poll** Flow for completion (the clip renders server-side, ~30–90s).
+4. **Download** the finished mp4 into `output_dir`.
+
+> **Do not close the browser window while a run is in progress.** Steps 3 and 4
+> still use the browser page (polling even brings it to the foreground). If the
+> window is closed before a scene finishes downloading, the in-flight scene
+> **aborts** — you will see a "Target/page/context closed" or `scene_failed`
+> error. **This is expected, not a bug.**
+
+If a run is interrupted (closed window, crash, network drop), it is **safe to
+re-run**: the sibling `<manifest>-state.json` records completed scenes (keyed on
+`scene.id`) and they are skipped, so the command resumes where it left off. A
+versioned handoff manifest (`<manifest>-handoff.json`) is always written at the
+end.
+
+> **Future — fire-and-forget.** Flow's status-poll and download endpoints are
+> non-generative and *could* be driven browser-free over Bearer REST (no
+> reCAPTCHA, no extra credits), letting the browser close right after submit
+> while gflow finishes over the API. That mode is **not implemented yet**; today
+> the browser is required for the full generate → poll → download cycle.
+
+## Character consistency (how the entity rides)
+
+A scene listing `characters = ["Stickman"]` is generated as **R2V**
+(reference-to-video) so the named Flow CHARACTER entity is reused. The entity is
+attached by driving Flow's resource picker:
+
+1. Click **Add Media** in the composer (references sub-mode).
+2. Switch to the **Personagens** (Characters) tab.
+3. **Right-click** the entity tile — addressed by entity id as
+   `data-tile-id="fe_id_<entityId>"` — and choose **"Incluir no comando"** from
+   the context menu. *(A plain left-click navigates into the character editor;
+   the inline "Incluir" button on the **Tudo** tab attaches the character's
+   thumbnail as a plain image, not the entity.)*
+
+This puts `referenceEntities:[{entityId}]` on the
+`video:batchAsyncGenerateVideoReferenceImages` **request**. Flow's **response**
+echoes the accepted entity at:
+
+```
+media[].mediaMetadata.requestData.videoGenerationRequestData
+      .videoGenerationEntityInputs[].entityId
+```
+
+gflow asserts this on every entity scene (`_assert_entities_attached`) and
+**refuses to report success** if the entity did not ride — a text/image-only
+clip is never silently passed off as character-consistent. The recorded
+`consistency_method` in the run state is `entity` when the entity rode (vs
+`text`).
+
+See [CHARACTER.md](CHARACTER.md) for the underlying entity model and
+[CHARACTER_RECON.md](CHARACTER_RECON.md) for the reverse-engineered wire
+protocol.
+
+## `movie run` options
+
+| Flag | Default | Effect |
+|------|---------|--------|
+| `--profile <name>` | default profile | Chrome profile to drive (must be a `chrome`-strategy profile). |
+| `--out-dir <dir>` | manifest `output_dir` | Override the output directory. |
+| `--dry-run` | off | Print the plan + credit estimate; make **no** API calls. |
+| `--fail-fast` / `--continue-on-error` | continue | Stop on the first scene failure, or attempt the rest (default). |
+| `--stitch` | off | After generating, hard-concat all clips into one preview mp4 (ffmpeg, no transitions). |
+
+## Credits
+
+- Character creation (image generation) is **free** — no credits, no reCAPTCHA.
+- Each **scene** is one video generation = **1 credit**, spent at submit (step 2
+  above). A `--dry-run` shows the estimate without spending anything.

{gflow_cli-0.13.0 → gflow_cli-0.15.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,9 @@
 
 ## Current release
 
-**v0.13.0 — alpha.** High-fidelity CLI hardening and term alignment. **`gflow video i2v`** now uses the canonical `--initial-frame` and `--end-frame` flags (matching Flow's UI labels), with robust Click greedy-fill protection and positional backward compatibility. **In-project governance** (ruff T20, materiality classification) is now active to harden the AI-driven development flow. This release also refactors the **`character_create` saga** for improved type safety and documentation. Live-verified end-to-end on 2026-06-04 with the new flags and interpolation paths.
+**v0.15.0 — alpha.** **Character-consistent images via entity references.** `gflow image t2i/i2i` can now reference locked Flow CHARACTER entities (`--reference-entity <id>`, repeatable) and generate in an existing project (`--project <id>`) where those entities live — entities attach through the editor's Personagens picker and ride the submit as `referenceEntities` (confirmed against the live API; the body builder serializes them for headless transports too). Live-verified 2026-06-08: a 3-frame Dragon-Hook smoke rendered drift-free with all three characters on-model. LLM-council-reviewed (security/correctness/dedup) before merge. Carries forward the v0.14.0 `gflow movie` line (multi-scene, character-consistent video).
 
-**Develop (unreleased, post-v0.13.0):** *(empty — develop is the staging branch for the next release).*
+**Develop (unreleased, post-v0.15.0):** *(empty — develop is the staging branch for the next release).*
 
 ## Milestone history
 
@@ -52,6 +52,8 @@
 | `gflow character rm` — free character deletion (#150) | ✅ done (v0.13.0) |
 | Align I2V CLI flags with Flow UI Labels (`--initial-frame`) (#122) | ✅ done (v0.13.0) |
 | In-project governance (ruff T20, materiality Classifier) | ✅ done (v0.13.0) |
+| `gflow movie` — multi-scene, character-consistent video from a TOML manifest (entity reuse, resumable, handoff manifest) | ✅ done (v0.14.0) |
+| `gflow image t2i/i2i` — reference locked CHARACTER entities (`--reference-entity`) + `--project` for character-consistent stills | ✅ done (v0.15.0) |
 | `gflow character` — reusable Flow Character entities (`create`/`list`/`show`/`voices`), persist-before-spend saga (#145) | ✅ done (v0.12.0) |
 | `gflow scene` — Add Clip / Scenes compose + credit-free server-side extended video (`runVideoFxConcatenation`) | ✅ done (v0.12.0) |
 | `gflow video chain` — last-frame I2V chaining from a JSONL manifest (`--dry-run`/`--max-links`/`--resume-from`) | ✅ done (v0.12.0) |

{gflow_cli-0.13.0 → gflow_cli-0.15.0}/docs/USAGE.md

@@ -131,6 +131,13 @@ Options:
                             Aspect ratio.                     [default: 9:16]
   -n, --count INTEGER       How many images to generate (1-4).  [default: 1]
   --out PATH                Output directory (see "Output paths" below).
+  --project ID              Generate in this EXISTING Flow project instead of a
+                            scratch project. Required to reference locked
+                            entities/assets in that project. Single-prompt only.
+  --reference-entity ID     Flow CHARACTER entity id to reference for character
+                            consistency (repeatable; must live in --project).
+                            Single-prompt only.
+  --reference-entity-name N Display name paired with --reference-entity.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -212,6 +219,10 @@ Options:
                             Aspect ratio.                     [default: 9:16]
   -n, --count INTEGER       How many images to generate (1-4).  [default: 1]
   --out PATH                Output directory (same semantics as t2i).
+  --project ID              Generate in this EXISTING Flow project (skip scratch).
+  --reference-entity ID     Flow CHARACTER entity id to reference (repeatable;
+                            must live in --project). Counts toward the ref cap.
+  --reference-entity-name N Display name paired with --reference-entity.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -248,6 +259,40 @@ A 2-image run produces files numbered `_1.png`, `_2.png`:
 ./variants/<media_name_b>_2.png
 ```
 
+## Character-consistent images (entity references)
+
+`--reference-entity` makes `image t2i`/`i2i` reference a locked Flow **CHARACTER
+entity** (minted via `gflow character create`) so the generated subject stays
+on-model across shots — no per-shot prompt wrangling or fragile image refs.
+
+How it works: entities are **project-scoped**, so you must generate **in the
+project that owns them** via `--project <id>` (this also means no throwaway
+scratch project is created). The CLI attaches each entity through the Flow editor's
+resource picker; the submit then carries `referenceEntities`, exactly like the
+video R2V path. Entities count toward the same per-model reference cap as `--ref`
+images. `--reference-entity` / `--project` are **single-prompt only**.
+
+For a *pure* character reference (no starting image) use `t2i` — `i2i` still
+requires at least one `--ref`.
+
+```bash
+# One locked character, consistent across runs (t2i = no image ref needed)
+gflow image t2i "Aria explores a neon market, full body" \
+  --project 7fa97443-… --reference-entity 8a77f8cb-… --reference-entity-name Aria \
+  --model nano2 --aspect 9:16 -n 3
+
+# Several characters in one scene (each --reference-entity repeatable)
+gflow image t2i "Aria and Drako meet at the gate" --project 7fa97443-… \
+  --reference-entity 8a77f8cb-… --reference-entity 4ed5cb7f-…
+
+# i2i: a starting image PLUS an entity for the character
+gflow image i2i "place this hero in a snowy pass" --ref hero.png \
+  --project 7fa97443-… --reference-entity 8a77f8cb-…
+```
+
+> Ids are validated at the CLI boundary (letters/digits/hyphens, ≤128 chars).
+> The entity must already exist in `--project` (see `gflow character create`).
+
 ## `gflow image batch`
 
 Generate multiple images from a single manifest file. The format is dispatched by file extension (`.json` or `.tsv`).

gflow_cli-0.15.0/docs/schemas/movie-handoff.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "gflow movie handoff manifest",
+  "type": "object",
+  "required": ["schema_version", "generator", "movie", "clips"],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "generator": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": { "name": { "type": "string" }, "version": { "type": "string" } }
+    },
+    "movie": {
+      "type": "object",
+      "required": ["title"],
+      "properties": {
+        "title": { "type": "string" },
+        "output_dir": { "type": "string" },
+        "total_duration_seconds": { "type": "number" }
+      }
+    },
+    "style": { "type": "object" },
+    "characters": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "identity"],
+        "properties": {
+          "name": { "type": "string" },
+          "identity": { "enum": ["text", "entity"] },
+          "voice": { "type": ["string", "null"] },
+          "x_gflow": { "type": "object" }
+        }
+      }
+    },
+    "clips": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "index", "file", "status"],
+        "properties": {
+          "id": { "type": "string" },
+          "index": { "type": "integer", "minimum": 0 },
+          "file": { "type": ["string", "null"], "pattern": "^[^\\\\]*$" },
+          "duration_seconds": { "type": ["number", "null"] },
+          "framing": { "type": ["string", "null"] },
+          "characters": { "type": "array", "items": { "type": "string" } },
+          "consistency_method": { "enum": ["text", "entity", "degraded"] },
+          "dialogue": { "type": "array" },
+          "prompt": { "type": ["string", "null"] },
+          "status": { "enum": ["completed", "failed"] },
+          "x_gflow": { "type": "object" }
+        }
+      }
+    },
+    "stitch": { "type": "object" }
+  }
+}