gflow-cli 0.11.0__tar.gz → 0.12.0__tar.gz

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/.claude/README.md

@@ -12,7 +12,10 @@ This directory holds **internal maintainer workflows** that are bundled with the
 └── commands/              ← repo-local slash commands
     └── gflow/             ← `/gflow:*` namespace (avoids collision with built-ins)
         ├── check.md       ← `/gflow:check` — hygiene + ruff + pyright + pytest
-        ├── plan.md        ← `/gflow:plan` — show active phase / superpowers plan
+        ├── status.md      ← `/gflow:status` — full plan state (file, goal, progress, next task)
+        ├── next.md        ← `/gflow:next` — next unchecked task only
+        ├── active.md      ← `/gflow:active` — which plan is active, goal only
+        ├── plan.md        ← `/gflow:plan <feature>` — create a task-by-task implementation plan
         ├── known-issues.md← `/gflow:known-issues` — open/mitigated items
         ├── changelog.md   ← `/gflow:changelog` — [Unreleased] + last tagged
         └── release.md     ← `/gflow:release` — full release flow (signed tags)

gflow_cli-0.12.0/.claude/commands/gflow/active.md

@@ -0,0 +1,13 @@
+---
+description: Show which plan is active and its goal — orientation without task detail.
+---
+
+# `/gflow:active` — Active plan identity
+
+**Read `skills/status/SKILL.md` and follow the `active` variant protocol.**
+
+> Do **not** call `Skill(skill="status")` — read the file directly.
+
+The skill at `skills/status/SKILL.md` runs `scripts/dev/active_plan.py` and returns
+only the header lines (Plan path, Title, Goal, Progress count). Stops before the
+`--- Next task ---` separator.

gflow_cli-0.12.0/.claude/commands/gflow/next.md

@@ -0,0 +1,12 @@
+---
+description: Show only the next unchecked task — minimal output, no context noise.
+---
+
+# `/gflow:next [feature]` — Next task
+
+**Read `skills/status/SKILL.md` and follow the `next` variant protocol**, passing `$ARGUMENTS` as the optional feature slug.
+
+> Do **not** call `Skill(skill="status")` — read the file directly.
+
+The skill at `skills/status/SKILL.md` runs `scripts/dev/active_plan.py` and returns
+only the `--- Next task ---` block. Header lines (Plan, Title, Goal, Progress) are omitted.

gflow_cli-0.12.0/.claude/commands/gflow/plan.md

@@ -0,0 +1,22 @@
+---
+description: Create a structured task-by-task implementation plan for a feature and write it to docs/superpowers/plans/.
+---
+
+# `/gflow:plan <feature>` — Create a feature plan
+
+**Read `skills/plan/SKILL.md` and follow its protocol now**, passing `$ARGUMENTS` as the feature description.
+
+> Do **not** call `Skill(skill="plan")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable. Read the file directly instead.
+
+The skill at `skills/plan/SKILL.md` gathers predict/scenario context, asks ≤3
+clarifying questions, decomposes the feature into atomic committable tasks with
+step + test checklists, and writes `docs/superpowers/plans/<date>-<slug>/PLAN.md`.
+
+**Typical workflow:**
+```
+/gflow:predict <proposal>   →  GO / CAUTION / STOP
+/gflow:scenario <feature>   →  edge cases + BDD skeleton
+/gflow:plan <feature>       →  writes PLAN.md  ← this command
+/gflow:status               →  surfaces next task
+/gflow:check                →  before each commit
+```

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/.claude/commands/gflow/predict.md

@@ -16,4 +16,10 @@ The skill at `skills/predict/SKILL.md` runs five independent expert personas
 (Architect · Security/reCAPTCHA · Performance/Playwright · CLI UX · Devil's Advocate),
 resolves conflicts, and returns a GO / CAUTION / STOP verdict with a confidence score.
 
-**Pair with `/gflow:scenario`** after a GO or CAUTION to enumerate edge cases before EXECUTE.
+**Typical workflow after a GO or CAUTION:**
+```
+/gflow:scenario <feature>   →  edge cases + BDD skeleton
+/gflow:plan <feature>       →  writes PLAN.md task checklist
+/gflow:status               →  surfaces next task during execution
+/gflow:check                →  before each commit
+```

gflow_cli-0.12.0/.claude/commands/gflow/status.md

@@ -0,0 +1,12 @@
+---
+description: Show current plan state — active plan file, goal, progress, and next unchecked task.
+---
+
+# `/gflow:status [feature]` — Current plan state
+
+**Read `skills/status/SKILL.md` and follow the `status` variant protocol**, passing `$ARGUMENTS` as the optional feature slug.
+
+> Do **not** call `Skill(skill="status")` — read the file directly.
+
+The skill at `skills/status/SKILL.md` runs `scripts/dev/active_plan.py` and returns
+the full output: plan file path, title, goal, progress (X/N), and next task block.

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/.gitignore

@@ -63,6 +63,9 @@ samples/*.captured.json # sandbox-recorded API exchanges may contain PII
 test_assets/smoke_*/
 test_assets/debug_*/
 
+# Phase-2 live-spike capture outputs — NEVER commit (may contain real API payloads)
+scripts/dev/_spike_out/
+
 # Live Flow traffic captures — NEVER commit (contain real Bearer tokens / API keys).
 # Diagnostic scripts MUST default-write here, NOT to samples/captured/.
 # Sanitised reference samples (no secrets) can still live under samples/captured/.
@@ -83,3 +86,6 @@ worktrees/
 
 # E2E test logs (live Flow runs — may contain account/profile names)
 .planning/e2e-logs/
+
+# Understand Anything (local knowledge graph)
+.understand-anything/

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/AGENTS.md

@@ -8,7 +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_data.py`, `cli_image.py`, `cli_run.py`, `cli_video.py`, `config.py`, `data/`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- 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/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).
 - 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)
@@ -28,7 +29,7 @@ If you can help unblock a pure HTTP transport (especially for video generation,
 - Copy `.env.template` to `.env.local`; never commit `.env.local`. It documents every env var.
 - Output goes to `./tmp/` for scripts/tests or `$GFLOW_CLI_OUTPUT_DIR` for CLI outputs (defaults to `./out/`).
 - One-time auth: `gflow auth login --browser chrome`. The `--browser chrome` flag is mandatory; the CLI fails fast on other strategies.
-- Use `/gflow:plan` to see the active phase before starting work; `/gflow:known-issues` before touching auth or reCAPTCHA code paths.
+- Use `/gflow:status` to see the current task before starting work; `/gflow:known-issues` before touching auth or reCAPTCHA code paths.
 
 ## Testing instructions — The Impeccable Routine
 
@@ -55,7 +56,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–16, where 16 is the `DataStoreError` family from `gflow_cli.data`). 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–21, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`). 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).
 
 ## PR instructions
@@ -89,7 +90,7 @@ The SkillOpt harness at `scripts/dev/skillopt/` measures how accurately each ski
 - **Mandates & routing rules** → [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md)
 - **Full docs index** → [docs/INDEX.md](docs/INDEX.md)
 - **Known issues** (read before touching auth / reCAPTCHA) → [KNOWN_ISSUES.md](KNOWN_ISSUES.md)
-- **Active phase & backlog** → [PLAN.md](PLAN.md) or run `/gflow:plan`
+- **Current task** → `/gflow:status` · **Create a feature plan** → `/gflow:plan <feature>` · **Full roadmap** → [PLAN.md](PLAN.md)
 - **Release protocol** → [RELEASE.md](RELEASE.md)
 
 ## Claude Code-specific notes

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/CHANGELOG.md

@@ -7,6 +7,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-06-03
+
+### Fixed
+
+- **Create-project generation failing when Flow opens the Agent _chat panel_.**
+  A follow-up to the earlier Agent-pill fix: Flow now also surfaces Agent mode as
+  a docked chat side-panel ("Untitled session") on some project opens, and while
+  it is up the in-composer Agent pill is absent from the DOM — so the pill-only
+  recovery could not find anything to click and generation still failed with
+  "mode-switch dropdown trigger not found". `_exit_agent_mode` now handles both
+  Agent shapes in one pass: it dismisses the chat panel (locale-stable, aria-free
+  structural close anchor) which reveals the pill, then turns the pill off,
+  looping until the media panel re-mounts. Keyed on the outcome (`crop_*` is
+  back), so it covers pill-only, panel-only, and panel-then-pill without assuming
+  which control is present.
+
+### Added
+
+- **`gflow character` command group — reusable Flow Character entities (#145).**
+  Mint a project-scoped **Character** (a named subject with reference images, an
+  optional voice, and an optional personality) so the same subject appears
+  consistently across generations:
+  - `gflow character create --project <pid> --name <name> --face-prompt "…"
+    [--body-prompt "…"] [--voice <Name>] [--personality "…"]
+    [--model nano2|nanopro]` — two-step generation: a **face** reference (slot 0),
+    then a self-contained **front/side/back triptych body** (slot 1) seeded by the
+    generated face. gflow injects its own triptych instruction, so one body
+    generation yields all three angles. Characters have **no aspect-ratio
+    control** and exactly two models — `nano2` (Nano Banana 2, default) and
+    `nanopro` (Nano Banana Pro). Generated images are **downloaded** to local (or
+    cloud) storage; the signed `fifeUrl` is used only at download and never
+    persisted.
+  - `gflow character list --project <pid>` — list every Character in a project.
+  - `gflow character show --project <pid> (--id <entityId> | --name <name>)` —
+    show one Character; an ambiguous `--name` exits 11.
+  - `gflow character voices` — list the 29-name Gemini voice catalog
+    (name / description / sample-url); `--voice` is validated case-insensitively.
+
+  The credited generation rides Flow's own page JS in the character editor
+  (Option B, UI passive-capture — a self-assembled direct POST is reCAPTCHA-403
+  walled); the structural calls (createEntity, workflow/entity PATCH,
+  projectInitialData) are credit-free REST. Creation runs as a
+  **persist-before-spend, crash-recoverable saga**: the `entityId` and each
+  completed slot are recorded before/as credits are spent, so a crashed run
+  resumes without orphaning a paid generation or double-charging. Live-verified
+  end-to-end on 2026-06-02 (face + triptych body, both bound, downloaded, read
+  back). See [docs/CHARACTER.md](docs/CHARACTER.md).
+
+- **`gflow video chain` — last-frame I2V chaining.** Render a JSONL manifest of
+  *links* into one continuous sequence: link 0 is a text-to-video generation,
+  and every later link is an image-to-video generation **seeded by the extracted
+  last frame of the previous clip**, giving visual continuity with no
+  server-side stitching. Each link is a sequential paid Veo generation (**one
+  credit per link**); a cost-confirmation gate (`-y`/`--yes` to skip),
+  `--dry-run` plan preview, `--max-links` cap (exit 11), and
+  `--resume-from <chain-id>` (skips already-paid links, no re-billing) make the
+  spend explicit and recoverable. Per-link wire-route checking aborts loudly if
+  Flow drops the seed frame and routes an i2v link to the text-only endpoint
+  (issue #125), so a misroute can never be reported as a successful chain.
+  Only the Veo 3.1 models (`veo-lite`/`veo-fast`/`veo-quality`/`veo-lite-lp`)
+  are accepted; `omni-flash` is rejected. Chain links are recorded locally
+  (SQLite migration `0005`) to drive `--resume-from`. The frame extractor uses
+  PyAV via a new optional **`[chain]`** extra (`pip install 'gflow-cli[chain]'`)
+  — no system ffmpeg required. Each link is saved as its own mp4; concatenating
+  the clips into one file is a separate step — use `gflow scene` (auto-concat is
+  deferred, see [KNOWN_ISSUES.md](KNOWN_ISSUES.md)).
+
+- **`gflow scene` command group (Add Clip / Scenes).** Compose ordered,
+  trimmable video clips into a Flow **Scene** over the credit-free aisandbox
+  REST surface (no reCAPTCHA, no credits):
+  - `gflow scene create --project <pid> <workflowId>[:<start>-<end>] [...]` —
+    compose a scene from one or more existing clips (repeat an id to duplicate;
+    optional per-clip trim in seconds).
+  - `gflow scene show --scene <sid> --project <pid>` — read back a scene's clip
+    order and trims.
+  - `gflow scene create … --output extended.mp4` — render the composed scene
+    into a single **extended video** via Flow's server-side concatenation
+    (`runVideoFxConcatenation`) — credit-free, no reCAPTCHA, **no ffmpeg**. The
+    combined MP4 is fetched inline and written locally (or to the configured
+    cloud `storage_uri`). `--force` overwrites an existing output.
+
+  Scene compositions are recorded locally (SQLite migration `0003`) — including
+  each clip's media id + trims, and the rendered extended-video path (migration
+  `0004`) — so a compose survives a later render failure and the output is
+  discoverable for recovery. The append-to-existing-scene verb (`add-clip`) is
+  deferred — see the project backlog.
+
 ## [0.11.0] — 2026-05-31
 
 ### Changed
@@ -1269,7 +1356,8 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.12.0...HEAD
+[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
 [0.10.0]: https://github.com/ffroliva/gflow-cli/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/ffroliva/gflow-cli/compare/v0.9.0...v0.9.1

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/CLAUDE.md

@@ -11,7 +11,8 @@
 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:
-   - Starting a feature → `/gflow:plan`
+   - 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`
@@ -38,4 +39,4 @@ The heredoc pattern (`$(cat <<'EOF' ... EOF)`) is only valid inside a `Bash` too
 
 ## Active phase
 
-See [PLAN.md](PLAN.md) or run `/gflow:plan` for the current detailed plan.
+See [PLAN.md](PLAN.md) or run `/gflow:status` for current task. Run `/gflow:plan <feature>` to create a new feature plan.

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/GEMINI.md

@@ -11,7 +11,8 @@
 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:
-   - Starting a feature → `/gflow:plan`
+   - 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`
@@ -24,4 +25,4 @@
 
 ## Active phase
 
-See [PLAN.md](PLAN.md) or run `/gflow:plan` for the current detailed plan.
+See [PLAN.md](PLAN.md) or run `/gflow:status` for current task. Run `/gflow:plan <feature>` to create a new feature plan.

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/KNOWN_ISSUES.md

@@ -65,6 +65,21 @@ a different 401** — it occurs on a profile that *is* verified and *can* create
 projects, specifically on the `aisandbox-pa.googleapis.com` generation
 endpoint, a different surface from the `labs.google` tRPC API.
 
+> **Related — L0 aisandbox Bearer auth (`feature/scene-add-clip`, 2026-05-31):**
+> the `aisandbox-pa` 401 is NOT a SAPISIDHASH issue — live verification proved
+> the real header is **`Authorization: Bearer ya29.<oauth>`** (the SPA's OAuth2
+> access token, fetched from `GET /fx/api/auth/session`). `page.request` 401s
+> because it sends cookies but not that token. The `gflow scene` groundwork now
+> fetches+caches the token and attaches the Bearer to the **`page.request` REST
+> path** (`_post_json` / `_patch_json`, host-scoped to `aisandbox-pa`) so
+> `uploadImage` / `scenes` / `commit` authenticate — see
+> [`docs/superpowers/plans/2026-05-31-l0-bearer-pivot.md`](docs/superpowers/plans/2026-05-31-l0-bearer-pivot.md).
+> **Live-verified 2026-05-31:** REST `uploadImage` returns 200
+> (`tests/e2e/test_aisandbox_auth_live.py`, credit-free).
+> **Liberating follow-up:** the same Bearer likely unlocks the `evaluate_fetch`
+> generation 401 above (and REST generation generally, modulo reCAPTCHA) —
+> deferred, not yet applied to that transport.
+
 **Scope.** The 401 affects every image-generation path uniformly on the
 `evaluate_fetch` transport (the live one): `test_e2e_single_image_gen` (C2,
 pre-existing), `test_e2e_generate_image_without_project_id` (PR #20,
@@ -446,6 +461,93 @@ sample is captured.
 
 ---
 
+### `gflow video chain` re-exposes the i2v→t2v silent-route risk (issue #125)
+
+- **Status:** Mitigated · **Severity:** Medium · **Affects:** `gflow video chain` (v0.12.0)
+
+Every chain link after the first is an image-to-video (I2V) generation seeded by
+the previous clip's last frame. The same silent-route defect that affects
+`gflow video i2v` ([issue #125](https://github.com/ffroliva/gflow-cli/issues/125))
+applies here: if the chosen model can't do i2v interpolation, Flow drops the
+seed frame and routes the request to the plain text-to-video endpoint
+(`batchAsyncGenerateVideoText`) — burning a credit for a text-only clip that
+breaks continuity, with no error from Flow.
+
+**Mitigation (two layers):**
+1. **Model pin.** `omni-flash` (the only model known to silently drop frames) is
+   removed from the chain `--model` choices, and the orchestrator rejects any
+   model whose `supports_i2v_interpolation()` is false **before any spend**
+   (`ModelModeIncompatibilityError`, exit 17).
+2. **Per-link wire-route abort.** For each seeded link the transport inspects the
+   captured generate-response URL; if it observes `batchAsyncGenerateVideoText`
+   for an i2v link it raises `WireFormatError` (logged
+   `ui_automation_video.i2v_routed_to_t2v`, issue #125) rather than reporting a
+   fake success. The chain aborts and preserves every link completed before the
+   failure (`ChainPartialError`).
+
+**Workaround:** stick to the Veo 3.1 models (`veo-lite` / `veo-fast` /
+`veo-quality` / `veo-lite-lp`); these are the only accepted chain models.
+
+---
+
+### `gflow video chain` continuity caveat — black / fade-out final frame
+
+- **Status:** Open · **Severity:** Low · **Affects:** `gflow video chain` (v0.12.0)
+
+Chain seeds each link with the **last frame** of the previous clip. If a clip
+fades to black (or to a near-empty frame) at its very end — common with
+cinematic prompts — the extracted seed frame is mostly black, so the next link
+starts from black and continuity visibly breaks.
+
+**Workaround:** pass `--seed-offset MS` to extract the seed frame a few hundred
+milliseconds **before** end-of-file, skipping the fade. For example
+`--seed-offset 200` seeds from 200 ms before EOF. Tune per the fade length of
+your prompts.
+
+---
+
+### `gflow video chain` outputs N clips, not one file — auto-concat is deferred
+
+- **Status:** Open (by design) · **Severity:** Low · **Affects:** `gflow video chain` (v0.12.0)
+
+A chain produces **N separate mp4s** (one per link), not a single stitched
+video. Auto-concatenation is deferred: Flow's server-side concatenation
+(`runVideoFxConcatenation`, used by `gflow scene`) is **project-scoped** — every
+clip must live in the same Flow project to be concatenated. But chain links are
+*generated* sequentially and generation cannot pin all links to one shared
+project, so there is no clip set the concat endpoint could combine at the end of
+a chain run.
+
+**Workaround:** stitch the link clips into one file with `gflow scene`
+(server-side, credit-free, no ffmpeg) after the chain completes. The chain
+prints its `chain_id` and a reminder to do this on success.
+
+**Roadmap:** wiring chain links into a single Flow project so the chain can
+auto-concat its own output is under consideration — tracked as backlog.
+
+---
+
+### `gflow video chain --resume-from` re-seeds the first resumed link as T2V
+
+- **Status:** Open · **Severity:** Low · **Affects:** `gflow video chain` (v0.12.0)
+
+`--resume-from <chain-id>` skips links already paid for in a prior run (they are
+**not** re-billed) and continues from the first incomplete link. However, the
+first resumed link is generated as a **text-to-video** link, not seeded from the
+last frame of the last completed link — there is no cross-run seed-frame
+hand-off yet. The resume is **credit-safe** (no double-billing), but visual
+continuity restarts at the resume point: the first resumed clip will not flow
+seamlessly from the clip before it.
+
+**Workaround:** if seamless continuity across a resume boundary matters, re-run
+the affected tail of the chain from scratch rather than resuming, or stitch with
+`gflow scene` and accept the cut at the resume boundary.
+
+**Roadmap:** persist and re-extract the boundary seed frame so a resumed link can
+continue as a seeded I2V generation — tracked as backlog.
+
+---
+
 ## Mitigated
 
 ### Auth verification depends on Google's NextAuth session endpoint

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.11.0
+Version: 0.12.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
@@ -45,7 +45,11 @@ Requires-Dist: pydantic-settings>=2.5.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: structlog>=24.0.0
 Requires-Dist: tenacity>=8.2
+Provides-Extra: chain
+Requires-Dist: av>=12; extra == 'chain'
 Provides-Extra: dev
+Requires-Dist: av>=12; extra == 'dev'
+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'
@@ -82,6 +86,7 @@ Description-Content-Type: text/markdown
 For Google AI Ultra / Pro subscribers with Veo credits and batch workloads:
 
 - **Burn credits efficiently** — `for p in $(cat prompts.txt); do gflow image t2i "$p"; done` _(image batching, plus `gflow video t2v`/`i2v`/`r2v`, all ship today)_
+- **Reuse a subject across shots** — `gflow character create` mints a Flow **Character** (face + body reference) so the same person appears consistently from generation to generation
 - **Build pipelines** — wire Veo into your content automation, AI video stack, or batch experiments
 - **Stay in the terminal** — no Chromium UI, no clicking through dialogs (after a one-time `gflow auth login`)
 
@@ -101,6 +106,8 @@ gflow auth login --browser chrome
 gflow image t2i "a hot air balloon over Tokyo at sunrise"
 # or:
 gflow video t2v "Slow cinematic push-in on a sunlit forest clearing" --aspect 16:9
+# or mint a reusable Character (face + body reference):
+gflow character create --project <id> --name "Aria" --face-prompt "..." --body-prompt "..."
 ```
 
 Outputs land under `$GFLOW_CLI_OUTPUT_DIR` unless
@@ -132,6 +139,7 @@ Reproduce the recording: [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (W
 |---|---|
 | 🎯 **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`) |
 | 🔐 **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) |
@@ -170,7 +178,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Project status
 
-**v0.11.0 — alpha.** Image (T2I / I2I / upload) + Video T2V / I2V / R2V live end-to-end on `ui_automation`, with a video `--model` picker (5 Veo models) + `--duration` / `--count`. v0.11.0 is a reliability release: it repairs `gflow video i2v` — on v0.10.0 every i2v run silently produced text-to-video output that ignored the start/end frames (issue #125) — fixes create-project generation when Flow's "Agent" composer mode is active, and hardens image-model selection for non-English Flow UIs (#94). New in v0.10.0: `--json` output across every generation command (`image t2i/i2i`, `video t2v/i2v/r2v`, `auth list`) plus a `gflow models` catalog so worker schedulers can drive the CLI machine-to-machine; per-model reference-image caps for `i2i`/`r2v`; profile Google-account identity persisted to disk (with auto-rename of the first-run `default` profile); external cloud storage (S3 / MinIO / GCS) via `GFLOW_CLI_STORAGE_URI`; and a `gflow data prune` maintenance command. Only video `batch` (manifest runner) is still queued for Phase B — use a shell for-loop until then ([USAGE](docs/USAGE.md#gflow-video-batch)). Full milestone history → [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md). Changelog → [CHANGELOG.md](CHANGELOG.md). Where the project is heading → [ROADMAP.md](ROADMAP.md).
+**v0.12.0 — alpha.** Three new capabilities. **`gflow character`** mints reusable, project-scoped Flow **Character** entities — a named subject with reference images, an optional voice, and an optional personality — so the same subject stays consistent across generations (`create` / `list` / `show` / `voices`, #145). **`gflow scene`** composes ordered clips into a scene and renders a credit-free, server-side **extended video** (no local ffmpeg). **`gflow video chain`** links last-frame image-to-video clips from a JSONL manifest into one continuous sequence. This release also fixes create-project generation when Flow surfaces Agent mode as a docked chat panel. Baseline: Image (T2I / I2I / upload) + Video T2V / I2V / R2V live end-to-end on `ui_automation`, with a video `--model` picker (5 Veo models) + `--duration` / `--count` (v0.11.0 repaired `gflow video i2v`, issue #125, and hardened image-model selection for non-English Flow UIs, #94; v0.10.0 added `--json` across every generation command, a `gflow models` catalog, per-model reference caps, persisted profile identity, external S3 / MinIO / GCS storage, and `gflow data prune`). Only video `batch` (manifest runner) is still queued for Phase B — use a shell for-loop until then ([USAGE](docs/USAGE.md#gflow-video-batch)). Full milestone history → [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md). Changelog → [CHANGELOG.md](CHANGELOG.md). Where the project is heading → [ROADMAP.md](ROADMAP.md).
 
 ## License & legal
 

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/PLAN.md

@@ -2,7 +2,7 @@
 
 > **Status:** Living document. Updated as phases complete.
 > **Owner:** [@ffroliva](https://github.com/ffroliva)
-> **Last revised:** 2026-05-31 (v0.11.0 release — `gflow video i2v` silent-T2V fix + `veo-lite` default (#125), create-project fix under Flow's "Agent" composer mode, image-model selector cascade for non-English UIs (#94))
+> **Last revised:** 2026-06-03 (v0.12.0 release — `gflow character` reusable Flow Character entities (#145), `gflow scene` Add Clip + credit-free server-side extended video, `gflow video chain` last-frame I2V chaining, create-project fix under Flow's Agent chat panel)
 
 This plan turns the v0.1 scaffold into a production-grade CLI for Google AI Ultra/Pro subscribers who want to spend their Flow credits via batch automation. The plan is opinionated, treating this repo as a portfolio-grade benchmark.
 

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/README.md

@@ -22,6 +22,7 @@
 For Google AI Ultra / Pro subscribers with Veo credits and batch workloads:
 
 - **Burn credits efficiently** — `for p in $(cat prompts.txt); do gflow image t2i "$p"; done` _(image batching, plus `gflow video t2v`/`i2v`/`r2v`, all ship today)_
+- **Reuse a subject across shots** — `gflow character create` mints a Flow **Character** (face + body reference) so the same person appears consistently from generation to generation
 - **Build pipelines** — wire Veo into your content automation, AI video stack, or batch experiments
 - **Stay in the terminal** — no Chromium UI, no clicking through dialogs (after a one-time `gflow auth login`)
 
@@ -41,6 +42,8 @@ gflow auth login --browser chrome
 gflow image t2i "a hot air balloon over Tokyo at sunrise"
 # or:
 gflow video t2v "Slow cinematic push-in on a sunlit forest clearing" --aspect 16:9
+# or mint a reusable Character (face + body reference):
+gflow character create --project <id> --name "Aria" --face-prompt "..." --body-prompt "..."
 ```
 
 Outputs land under `$GFLOW_CLI_OUTPUT_DIR` unless
@@ -72,6 +75,7 @@ Reproduce the recording: [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (W
 |---|---|
 | 🎯 **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`) |
 | 🔐 **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) |
@@ -110,7 +114,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 ## Project status
 
-**v0.11.0 — alpha.** Image (T2I / I2I / upload) + Video T2V / I2V / R2V live end-to-end on `ui_automation`, with a video `--model` picker (5 Veo models) + `--duration` / `--count`. v0.11.0 is a reliability release: it repairs `gflow video i2v` — on v0.10.0 every i2v run silently produced text-to-video output that ignored the start/end frames (issue #125) — fixes create-project generation when Flow's "Agent" composer mode is active, and hardens image-model selection for non-English Flow UIs (#94). New in v0.10.0: `--json` output across every generation command (`image t2i/i2i`, `video t2v/i2v/r2v`, `auth list`) plus a `gflow models` catalog so worker schedulers can drive the CLI machine-to-machine; per-model reference-image caps for `i2i`/`r2v`; profile Google-account identity persisted to disk (with auto-rename of the first-run `default` profile); external cloud storage (S3 / MinIO / GCS) via `GFLOW_CLI_STORAGE_URI`; and a `gflow data prune` maintenance command. Only video `batch` (manifest runner) is still queued for Phase B — use a shell for-loop until then ([USAGE](docs/USAGE.md#gflow-video-batch)). Full milestone history → [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md). Changelog → [CHANGELOG.md](CHANGELOG.md). Where the project is heading → [ROADMAP.md](ROADMAP.md).
+**v0.12.0 — alpha.** Three new capabilities. **`gflow character`** mints reusable, project-scoped Flow **Character** entities — a named subject with reference images, an optional voice, and an optional personality — so the same subject stays consistent across generations (`create` / `list` / `show` / `voices`, #145). **`gflow scene`** composes ordered clips into a scene and renders a credit-free, server-side **extended video** (no local ffmpeg). **`gflow video chain`** links last-frame image-to-video clips from a JSONL manifest into one continuous sequence. This release also fixes create-project generation when Flow surfaces Agent mode as a docked chat panel. Baseline: Image (T2I / I2I / upload) + Video T2V / I2V / R2V live end-to-end on `ui_automation`, with a video `--model` picker (5 Veo models) + `--duration` / `--count` (v0.11.0 repaired `gflow video i2v`, issue #125, and hardened image-model selection for non-English Flow UIs, #94; v0.10.0 added `--json` across every generation command, a `gflow models` catalog, per-model reference caps, persisted profile identity, external S3 / MinIO / GCS storage, and `gflow data prune`). Only video `batch` (manifest runner) is still queued for Phase B — use a shell for-loop until then ([USAGE](docs/USAGE.md#gflow-video-batch)). Full milestone history → [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md). Changelog → [CHANGELOG.md](CHANGELOG.md). Where the project is heading → [ROADMAP.md](ROADMAP.md).
 
 ## License & legal
 

{gflow_cli-0.11.0 → gflow_cli-0.12.0}/docs/AGENT_GUIDE.md

@@ -23,9 +23,20 @@ These are non-negotiable. They override default agent behavior where conflicts e
 - **Back-merge `main → develop` after every release.** See the `release-back-merge-gap-recovery` runbook in agent memory.
 - **Enforce model-dependent reference caps.** Flow's R2V (reference-to-video) and I2I (image-to-image) reference image caps are model-dependent (Omni=7, Veo Lite/Fast=3, Quality=0). These MUST be enforced at both the Domain layer (`GenerateVideoRequest`) and the CLI layer. Use `reference_cap_for(model)` and include event-based tripwires in E2E tests.
 
+## Command surfaces
+
+The `gflow` CLI exposes these command groups (full reference in [docs/USAGE.md](USAGE.md)):
+
+- `gflow auth` — one-time Chrome login, status, logout.
+- `gflow image` — `t2i` / `i2i` / `upload` (Imagen / Nano Banana).
+- `gflow video` — `t2v` / `i2v` / `r2v` / `batch`, plus `chain` (last-frame I2V chaining from a JSONL manifest; link 0 is t2v, later links are i2v seeded by the previous clip's last frame; veo models only).
+- `gflow character` — `create` / `list` / `show` / `voices`: reusable, project-scoped Flow Character entities (a named subject with reference images, optional voice and personality) for consistent subjects across generations. See [docs/CHARACTER.md](CHARACTER.md).
+- `gflow scene` — `create` / `show`: compose ordered clips into a scene; `create --output` renders a credit-free server-side extended video via `runVideoFxConcatenation` (no local ffmpeg).
+- `gflow data` — query the local SQLite catalog.
+
 ## Routing rules
 
-- **Starting a feature?** Run `/gflow:plan` first to see the active phase scope and definition of done.
+- **Starting a feature?** Run `/gflow:status` to see the active phase scope, then `/gflow:predict` → `/gflow:scenario` → `/gflow:plan <feature>` to create a task checklist.
 - **Touching auth, reCAPTCHA, browser flow, or anything previously flagged?** Run `/gflow:known-issues` first.
 - **Cutting a release?** Run `/gflow:release` — it sequences `/gflow:changelog`, `/gflow:check`, `/gflow:doc-review`.
 - **Before any commit:** Run `/gflow:check` (or the Impeccable Routine in AGENTS.md), including the documentation link gate.