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

{gflow_cli-0.11.0 → gflow_cli-0.13.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.13.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.13.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.13.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.13.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.13.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.13.0}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
           fetch-depth: 0  # full history so gitleaks can diff against base
 
       - name: Run gitleaks
-        uses: gitleaks/gitleaks-action@v2
+        uses: gitleaks/gitleaks-action@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

gflow_cli-0.13.0/.github/workflows/governance-advisory.yml

@@ -0,0 +1,33 @@
+name: Governance advisory
+
+# Non-blocking governance signal: classifies touched paths (material vs routine)
+# and surfaces a recommendation to run /gflow:predict + council review. It NEVER
+# fails the build and is NOT a required check — mirrors the reference AI-DLC
+# orchestrator's advisory-by-default risk gate. Hard enforcement (--block-on +
+# branch protection) is a conscious, documented deferral.
+
+on:
+  pull_request:
+
+# Least privilege: the script writes to $GITHUB_STEP_SUMMARY (no token needed).
+# read-only is sufficient; we do not post comments (which forks cannot do).
+permissions:
+  contents: read
+
+jobs:
+  materiality:
+    name: Materiality + traceability (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history so `git diff origin/<base>..HEAD` resolves
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Classify touched paths (advisory, never blocks)
+        run: |
+          git fetch --no-tags origin "${{ github.base_ref }}" || true
+          uv run python scripts/ci/check_materiality.py \
+            --base "origin/${{ github.base_ref }}"

gflow_cli-0.13.0/.github/workflows/governance-benchmark.yml

@@ -0,0 +1,29 @@
+name: Governance benchmark
+
+# Periodic calibration of the advisory materiality gate. Replays git history and
+# writes the false-positive / coverage report to the job summary. This is a
+# DASHBOARD, not a gate: non-blocking, read-only, no token (fork-safe). See
+# docs/GOVERNANCE_BENCHMARK.md.
+
+on:
+  schedule:
+    - cron: "0 6 1 * *" # 06:00 UTC on the 1st of each month
+  workflow_dispatch: # manual run from the Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  backtest:
+    name: Materiality gate backtest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history — the backtest replays every commit
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Run backtest (advisory; writes to job summary)
+        run: uv run python scripts/dev/materiality_backtest.py >> "$GITHUB_STEP_SUMMARY"

{gflow_cli-0.11.0 → gflow_cli-0.13.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.13.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/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), and `gflow data` (catalog queries).
 - 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.13.0}/CHANGELOG.md

@@ -7,6 +7,139 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-06-04
+
+### Added
+
+- **`gflow character rm` — delete a Character entity (#150).**
+  `gflow character rm --project <id> (--id <entityId> | --name <name>) [-y/--yes] [--json]`
+  deletes a Character via `POST flow:batchDeleteAssets` (Bearer; **FREE** — no
+  reCAPTCHA, no credit). Resolves by id or exact name (ambiguous name exits
+  **11**); prompts for confirmation unless `--yes`/`--json`.
+
+- **In-project governance enforcement (advisory-first).** Made the AI-driven
+  development flow followable and partly machine-enforced in-repo, modeled on the
+  reference AI-DLC governance orchestrator's advisory-by-default behavior:
+  ruff `T20` now bans raw `print()` in `src/`; an advisory branch-naming check and a
+  non-blocking materiality + traceability classifier (`scripts/ci/check_materiality.py`
+  + `governance-advisory.yml`) recommend `/gflow:predict` + council review when
+  sensitive paths (`auth/`, `api/transports/`, `api/client.py`, `_sapisidhash.py`,
+  `data/`, `recaptcha`) are touched, without ever blocking a merge. A
+  history-replay backtest (`scripts/dev/materiality_backtest.py`) calibrates the
+  gate — it measured a 1.1% false-positive rate (vs. a 20-30% estimate) and
+  raised fix-coverage from 61% to 74% by surfacing auth-token plumbing that lived
+  outside `auth/`. The backtest is a first-class, repeatable artifact (`--json`
+  mode, a monthly `governance-benchmark.yml` dashboard job) fully documented in
+  [`docs/GOVERNANCE_BENCHMARK.md`](docs/GOVERNANCE_BENCHMARK.md); the gate itself is
+  described in
+  [`docs/AGENT_GUIDE.md` § Governance & Enforcement](docs/AGENT_GUIDE.md#governance--enforcement).
+
+### Changed
+
+- **`gflow video i2v` frame flags aligned with Flow UI terminology (#122).**
+  `--initial-frame FILE` is the new canonical flag for the start image (matches
+  Flow's "initial frame" label). `--end-frame FILE` replaces `--end-image` as the
+  canonical end-frame flag. `--end-image` is kept as a **deprecated alias** (emits
+  `DeprecationWarning`; will be removed in a future minor release). The positional
+  `IMAGE` argument remains supported for back-compatibility.
+
+### Fixed
+
+- **Character editor 404 on non-English locales (#153).** `gflow character`'s
+  editor URL interpolated the locale verbatim, so the genuine default BCP-47
+  `en-US` produced `/fx/en-US/…`, which 404s the Flow character editor (only the
+  short primary subtag is a valid `/fx/<seg>/` segment). `character_editor_url`
+  now normalizes a BCP-47 tag to its lower-cased short segment (`en-US → en`,
+  `pt-BR → pt`), so the tool stays language-agnostic with the real default
+  locale.
+
+## [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
@@ -557,7 +690,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `gflow image batch` now actually shares one Flow project across all
   prompts in a batch. Previously the `--same-project=1` flag was a no-op
   at the `ui_automation` transport layer; each prompt landed in its own
-  Flow project. ([spec](docs/superpowers/specs/2026-05-22-stay-mounted-batch-session-design.md))
+  Flow project.
 - `gflow image t2i -n N` now makes one transport call using Flow's native
   xN count selector instead of fanning out N parallel single-image
   submissions. Closes [#14](https://github.com/ffroliva/gflow-cli/issues/14) part 1.
@@ -1269,7 +1402,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.11.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...HEAD
+[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
 [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.13.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.13.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.13.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.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.11.0
+Version: 0.13.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,11 +45,15 @@ 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'
-Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.15; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
@@ -77,11 +81,13 @@ Description-Content-Type: text/markdown
 >
 > 🌐 **Headed-browser today.** gflow drives Flow via a persistent Playwright Chromium profile — Google's auth + reCAPTCHA gates currently require it. See [Architecture & current limitations](#architecture--current-limitations) for the contributor opportunity.
 
+
 ## Why gflow-cli?
 
 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 +107,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,11 +140,13 @@ 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) |
+| 🏗️ **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) |
 | 🤝 **Contributing** | [Contributing](CONTRIBUTING.md) · [Development](docs/DEVELOPMENT.md) · [GitHub workflow](docs/GITHUB.md) |
 
+
 ## For AI agents & LLMs
 
 gflow-cli ships three agent entry points — pick the one your tool reads first.
@@ -170,7 +180,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.13.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.