gflow-cli 0.21.0__tar.gz → 0.22.0__tar.gz

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/.claude/commands/gflow/pr-council-review.md

@@ -8,4 +8,10 @@ description: Multi-dimensional LLM council review of an open PR. Five baseline d
 
 > Do **not** call `Skill(skill="pr-council-review")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking it errors with `Unknown skill: pr-council-review`. Read the file directly instead.
 
+**Required gate — SonarCloud must be green.** The council reviews the *diff*; it does
+not see SonarCloud's verdict. Before declaring the final verdict, run **`/gflow:sonar`**
+for this PR — the `SonarCloud analysis` gate must be green (zero new issues). A red gate
+is a blocking finding regardless of the council's own conclusions; report it with the
+exact failing conditions and do not call the PR merge-ready until it is green.
+
 Sibling: `/review` is the single-agent Claude-Code built-in (fast, one-pass). Use it for spot-checks; use this command for pre-merge multi-dim audits.

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/.claude/commands/gflow/release.md

@@ -198,8 +198,10 @@ gh pr create --base main --head chore/release-v<NEW_VERSION> \
   --title "chore(release): v<NEW_VERSION>"
 ```
 
-Wait for PR CI to go green (`gh pr checks <N> --watch`), then merge with a **merge
-commit** — never squash:
+Wait for PR CI to go green (`gh pr checks <N> --watch`). **The `SonarCloud analysis`
+check must be green (gate passed) — not just the test matrix.** If it is red or you
+want the verdict, run `/gflow:sonar <N>` and drive it to zero before merging. Then
+merge with a **merge commit** — never squash:
 
 ```bash
 gh pr merge <N> --merge --delete-branch

gflow_cli-0.22.0/.claude/commands/gflow/sonar.md

@@ -0,0 +1,82 @@
+---
+description: Check the SonarCloud quality gate for a PR (or the current branch) and drive it to zero. Reports GREEN, or the exact PR-scoped new issues/hotspots/coverage gaps to fix.
+---
+
+# `/gflow:sonar [PR#]` — SonarCloud quality gate
+
+The reusable Sonar primitive. `/gflow:check` is **local** and cannot see Sonar (it
+is server-side, post-push); `/gflow:pr-council-review` is an LLM diff review, not the
+gate verdict. This command answers one question: **is the SonarCloud gate green
+(zero new issues) for this PR, and if not, exactly what must be fixed?**
+
+`$ARGUMENTS` is the PR number. If empty, resolve it from the current branch
+(`gh pr view --json number -q .number`).
+
+Project: key `ffroliva_gflow-cli`, org `ffroliva-github` (see `sonar-project.properties`).
+The CI scan sets `sonar.qualitygate.wait=true`, so a **green `SonarCloud analysis`
+check means the gate genuinely passed** — but the gate **API is stale until that
+check finishes**, so always check the GitHub check FIRST.
+
+## Steps
+
+**1. Check the GitHub check first (never trust the gate API while it's pending).**
+
+```bash
+gh pr checks <N> --json name,state,bucket | \
+  jq -r '.[] | select(.name=="SonarCloud analysis") | "\(.bucket) \(.state)"'
+```
+
+- `pass` → **gate is GREEN / zero new issues. Done.** Report GREEN and stop.
+- `pending` → the SonarCloud job (~50s) runs *after* the ~3.5min test matrix; wait
+  (`gh pr checks <N> --watch`) before reading the API, or the API returns the
+  previous commit's verdict.
+- `fail` → continue to step 2 to enumerate the exact failing conditions.
+
+**2. Enumerate the failing conditions (PR-scoped — this is the #1 gotcha).**
+
+New-code issues live on the PR branch, NOT `main`. **Scope every call with
+`&pullRequest=<N>`** or the API reports 0 and you chase phantoms. Token is in
+`.env.local` as `SONAR_TOKEN` — read it inside a sandbox so it never lands in chat.
+`curl` may be blocked by the context-mode hook → use `ctx_execute` (javascript
+`fetch` with `Authorization: Basic base64(token+":")`).
+
+```bash
+# Which gate conditions are ERROR:
+GET /api/qualitygates/project_status?projectKey=ffroliva_gflow-cli&pullRequest=<N>
+# New issues (bugs/smells) with file:line + rule + creationDate:
+GET /api/issues/search?componentKeys=ffroliva_gflow-cli&pullRequest=<N>&resolved=false
+# Unreviewed security hotspots:
+GET /api/hotspots/search?projectKey=ffroliva_gflow-cli&pullRequest=<N>&status=TO_REVIEW
+```
+
+**3. Fix by condition — no gaming.**
+
+- **`new_coverage < 80%`** → add **real** unit tests for the uncovered new lines
+  (usually a new orchestration/`_run_*`/helper). There is NO mark-safe shortcut and
+  NEVER widen `sonar.coverage.exclusions` to dodge it.
+- **`new_code_smells` / `new_maintainability_rating` (e.g. S1192 duplicated literal,
+  S3776 cognitive complexity)** → fix at source. For a duplicated literal your diff
+  merely *touched*, collapse it to one module-scope alias so it falls under the
+  threshold (pyright/tests prove it's safe). For S7497, re-raise swallowed
+  `asyncio.CancelledError`.
+- **`new_security_hotspots_reviewed < 100%`** → only for a **genuine** false positive:
+  `POST /api/hotspots/change_status` form body
+  `hotspot=<key>&status=REVIEWED&resolution=SAFE&comment=<justification>` (204 = ok),
+  then **re-run the SonarCloud job** so it reposts the GitHub status
+  (`gh run rerun <run-id> --job <sonar-job-id>` — the coverage artifact is reused).
+  Never mark a real hotspot SAFE.
+
+**4. Push fixes, then re-verify from step 1** (the check must read `pass`).
+
+## Output
+
+- Verdict: **GREEN** (gate passed, zero new issues) or **RED** with the exact failing
+  conditions and a fix list (`file:line · rule · what to do`).
+- After any fix: re-confirm via step 1 — green check = gate passed.
+
+## See also
+
+- `docs/GITHUB.md` § SonarCloud Quality Gate — full policy + coverage-exclusion rationale.
+- `/gflow:check` — the local pre-commit gates (coverage floor pre-empts `new_coverage`).
+- Memory: [[sonarcloud-pr-issues-scope-s7497]], [[sonarcloud-new-code-gotchas]],
+  [[sonarcloud-hotspot-review-workflow]], [[sonarcloud-setup]].

gflow_cli-0.22.0/.github/workflows/main-base-guard.yml

@@ -0,0 +1,50 @@
+name: Guard main base
+
+# Blocks the divergence class that bit v0.21.0: a non-release branch merged
+# straight into `main` (PR #203 — base mistakenly set to `main`, then squashed),
+# which bypassed `develop` and skipped the `main -> develop` back-merge, leaving
+# `main` ahead of `develop` by an orphaned squash commit.
+#
+# Policy: only `chore/release-*` (cut by /gflow:release) or `hotfix/*` branches
+# may target `main`. Everything else must go through `develop` (the default /
+# integration branch). Dependabot and normal PRs already default to `develop`,
+# so this only catches a deliberate, mistaken `--base main`.
+#
+# The job runs on EVERY PR and passes trivially when the base is not `main`, so
+# it is safe to mark as a *required* status check on `main` without blocking
+# `develop` PRs (which would otherwise hang as "expected — waiting").
+
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  guard:
+    name: Only release/hotfix branches may target main
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify base/head pairing
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          echo "PR head '$HEAD_REF' -> base '$BASE_REF'"
+          if [ "$BASE_REF" != "main" ]; then
+            echo "Base is '$BASE_REF' (not main) — nothing to enforce."
+            exit 0
+          fi
+          case "$HEAD_REF" in
+            chore/release-*|hotfix/*)
+              echo "OK: '$HEAD_REF' is allowed to target 'main'."
+              ;;
+            *)
+              echo "::error title=Wrong base branch::PR head '$HEAD_REF' must not target 'main'."
+              echo "Only 'chore/release-*' (via /gflow:release) or 'hotfix/*' branches may merge into 'main'."
+              echo "Feature, CI, fix, docs, and dependency work must target 'develop' (the integration branch)."
+              echo "Fix: re-target this PR to 'develop', or — if this really is a release — rename the branch to 'chore/release-vX.Y.Z'."
+              exit 1
+              ;;
+          esac

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/.gitignore

@@ -32,12 +32,15 @@ htmlcov/
 .DS_Store
 
 # Project-specific — secrets / session storage (NEVER commit)
-auth/                  # any project-local auth dir
-profile_*/             # Chromium persistent contexts (any name)
-*.cookies.json         # exported cookie jars
-storage_state.json     # Playwright storage_state output
-secrets.json           # generic secrets file
-.env                   # local env overrides (the .env.template IS committed)
+# NOTE: git does NOT support trailing inline comments in .gitignore — a `#` only
+# starts a comment at the START of a line. Keep each pattern on its own line so
+# the comment text isn't folded into the pattern (which silently un-ignores it).
+/auth/
+profile_*/
+*.cookies.json
+storage_state.json
+secrets.json
+.env
 .env.local
 .env.*.local
 
@@ -93,3 +96,6 @@ worktrees/
 # Understand Anything (local knowledge graph)
 .understand-anything/
 .worktrees
+
+# Subagent-driven-development scratch (ledger + task reports)
+.superpowers/

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/AGENTS.md

@@ -50,6 +50,7 @@ Or invoke the wrapper: `/gflow:check`.
 - Use `pytest -m "not live and not e2e and not smoke"` locally; full suite OOMs on small dev machines. Scope to changed dirs; trust CI for the full sweep.
 - TDD is non-negotiable. Coverage floor: 80% overall.
 - Documentation is a first-class deliverable. Every behavior, workflow, config, or operator-facing change must update the relevant docs or state why no docs changed in the PR/checklist. `scripts/ci/check_doc_links.py` is a merge gate.
+- **A PR is not done until its SonarCloud gate is green (zero new issues).** The six gates above are local/pre-commit; SonarCloud is server-side and runs in CI (`sonar.qualitygate.wait=true` → a red gate turns the `SonarCloud analysis` check red). Before calling a PR merge-ready, verify it with `/gflow:sonar <N>` (it is skipped on fork PRs — maintainer-checked there).
 - Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`. E2E tests require `GFLOW_CLI_E2E_PROFILE`.
 
 ## Code style

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] — 2026-06-28
+
+### Added
+
+- **Tools framework ("Creative Director")**: a TOML-defined prompt-tool system with
+  `creative-director` as the first built-in tool, exposed via two surfaces:
+  - **`gflow tools list/show/run`** — discover tools, inspect their styles, and run them
+    standalone (e.g. `gflow tools run creative-director "a cat" --style cinema --json`).
+  - **`-t` / `--tool` option** on every generation command — `image t2i` / `i2i` / `batch`,
+    `video t2v` / `i2v` / `r2v` / `chain` — apply one or more tools before generating
+    (e.g. `--tool creative-director:style=cinema`). Repeatable. On multi-prompt batches and
+    chains the tool is applied per prompt/link. Replaces the never-released `-e/--expand` flag.
+  - The `creative-director` tool rewrites a terse prompt into a vivid one using Google's
+    five-component formula (Subject + Action + Context/Location + Composition/Camera + Style)
+    via the public Gemini API. Requires `GFLOW_CLI_GEMINI_API_KEY`
+    ([get one](https://aistudio.google.com/apikey)); optional `GFLOW_CLI_GEMINI_MODEL`
+    (default `gemini-2.5-flash`). Domain-vocabulary modes (`--style cinema`, `portrait`,
+    `product`, etc.) inject specialized lens/lighting/colour vocabulary; styles are
+    **category-gated**, so image styles apply to image commands and video styles to video.
+  - Tool application is **never fatal** — missing key, rate limit, or any API/network fault
+    degrades gracefully to the original prompt.
+  - **History**: a generation rewritten by a tool records the user's original prompt in the
+    `prompt` column, the submitted expansion in `expanded_prompt`, and the applied tool
+    (`{name, version, model, params, config_hash}`) in `operations.metadata_json.tool` — all
+    honoring `GFLOW_CLI_HISTORY_PROMPTS=redacted` (the redacted form stores only
+    `{name, version, params_hash, config_hash}`).
+  - MCP parity: `gflow_list_tools` tool and a `tools` array parameter (`[{name, options}]`) on
+    `gflow_generate_image` / `gflow_generate_video`, validated and adapted to the CLI
+    `--tool` form.
+  - **"My Tools"**: drop your own tool TOMLs into `<GFLOW_CLI_HOME>/tools/*.toml` and they are
+    registered automatically — listed by `gflow tools list`, usable via `--tool`, and exposed over
+    MCP, just like built-ins. A user tool may override a built-in of the same name (logged via
+    `tool_user_override`); a malformed user TOML fails loud. See [docs/TOOLS.md](docs/TOOLS.md).
+  - The Gemini prompt expander gained an overall **wall-clock budget** (default ~60s per call)
+    on top of the lowered 20s per-attempt timeout, so sustained rate limiting can no longer
+    block a generation for the full retry schedule before falling back to the original prompt.
+
+### Deprecated
+
+- **`expand_prompt` MCP prompt**: superseded by the `creative-director` tool, which performs the
+  rewrite server-side (calls Gemini, strips banned keywords, supports domain styles, records
+  provenance). The prompt still works and now carries a `[DEPRECATED]` marker in its
+  client-visible description; it is slated for removal in a future major release. Use
+  `gflow tools run creative-director` / `--tool` (CLI) or `gflow_list_tools` + the `tools` array
+  param (MCP) instead.
+
 ## [0.21.0] — 2026-06-26
 
 ### Added
@@ -1582,7 +1628,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.21.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/ffroliva/gflow-cli/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/ffroliva/gflow-cli/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/ffroliva/gflow-cli/compare/v0.20.0...v0.20.1
 [0.20.0]: https://github.com/ffroliva/gflow-cli/compare/v0.19.0...v0.20.0

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/CONFIGURATION.md

@@ -9,6 +9,8 @@
 | `GFLOW_CLI_BROWSER` | `auto` | Browser mode. See **Browser mode** section below. |
 | `CHROME_BINARY` | (autodetect) | Override Chrome binary path. Falls back to platform-standard locations. |
 | `GFLOW_CLI_CONCURRENCY` | `4` | Maximum parallel API requests per batch. |
+| `GFLOW_CLI_GEMINI_API_KEY` | _(unset)_ | Public Gemini key enabling prompt expansion (`-e`/`--expand`). Unset = expansion is a graceful no-op. [Get one](https://aistudio.google.com/apikey). |
+| `GFLOW_CLI_GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model used for prompt expansion. |
 | `GFLOW_LIVE` | _(unset)_ | Set to `1` to enable live-API test markers (`@pytest.mark.live`). |
 
 ---

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/CONTRIBUTING.md

@@ -102,6 +102,23 @@ pip install pre-commit && pre-commit install
 
 The `.pre-commit-config.yaml` already ships ruff and the hygiene gate.
 
+### SonarCloud quality gate
+
+On top of the six gates, CI runs a **SonarCloud** analysis whose quality gate must be
+**green** before a PR is merge-ready — the target is **zero new issues** on changed code
+(new bugs, vulnerabilities, and code smells = 0; coverage of new lines ≥ 80%; security
+hotspots reviewed = 100%). The local `--cov-fail-under=80` gate already pre-empts the
+coverage condition, so if your tests are green locally you have usually cleared the part
+of the gate you can run yourself.
+
+SonarCloud is **server-side and maintainer-run**: it needs a repo secret (`SONAR_TOKEN`)
+that, for security, GitHub does **not** share with pull requests from forks. So **on a
+fork PR the SonarCloud check is skipped** — you cannot run it, and that is expected. A
+maintainer checks the gate before merging (and, for fork PRs, may re-run the branch
+internally to produce an analysis). Don't worry if you see the SonarCloud check absent or
+skipped on your PR; focus on keeping the six local gates green and your diff free of new
+smells. Full policy: [`docs/GITHUB.md`](docs/GITHUB.md) § SonarCloud Quality Gate.
+
 ### Script output convention
 
 All runtime output — smoke runs, debug dumps, generated images — **must** go

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.21.0
+Version: 0.22.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
@@ -94,6 +94,7 @@ You pay for Google AI Ultra or Pro, you have Veo credits, and you run real batch
 
 - **Batch generation.** Loop prompts straight from the shell: `for p in $(cat prompts.txt); do gflow image t2i "$p"; done`. Image batching plus `gflow video t2v` / `i2v` / `r2v` all ship today.
 - **Consistent subjects.** `gflow character create` mints a Flow Character (face and body reference) so the same person appears from one generation to the next.
+- **Prompt tools.** `--tool creative-director` rewrites a terse prompt into a vivid one (Google's 5-component formula) before generating — on any command. Bring your own with [My Tools](docs/TOOLS.md).
 - **Pipelines.** Wire Veo into your content automation, AI-video stack, or batch experiments.
 - **Terminal-native.** After one `gflow auth login`, you stay in the shell. No clicking through dialogs.
 

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/PLAN.md

@@ -359,7 +359,13 @@ The video-generation feature has its own sub-phase plan (spike → Phase A → P
   - **Phase 4 (Task #6, 2026-05-26, branch `claude/next-quick-win-gBPqS`, PR #93):** `NEW_PROJECT_SELECTORS` expanded to all 14 locales (icon-first tier + 14-locale text tier); English-only ARIA fallbacks (`[aria-label*='New project']`, `[aria-label*='Project']`) removed. `SUBMIT_BUTTON_SELECTORS` drops its English-only `button[aria-label*="Create"]` entry — `arrow_forward` icon selectors cover it in all locales. Both tuples are now fully locale-invariant. Note: issue #24 was closed 2026-05-24 after Phases 1–3; Phase 4 is cosmetic tail work. `--lang=en-US` retained only to stabilise `IMAGE_MODEL_OPTION_SELECTORS` (product names like "Nano Banana 2" may be localised). Removing it requires converting the image model picker to a structural anchor — tracked as issue #94 (Phase 5 below). **R2V live e2e on non-EN not yet exercised** — still open.
   - **Phase 5 (2026-05-30, branch `claude/issue-94-staleness-check-MnsEY`, PR #127):** `IMAGE_MODEL_OPTION_SELECTORS` and `VIDEO_MODEL_OPTION_SELECTORS` converted from `dict[Model, str]` to `dict[Model, tuple[str, ...]]` (cascade discipline; Tier 1 structural slots reserved for future DOM-probe-confirmed anchors). `--lang=en-US` removed from Chromium launch args — locale controlled by `locale=locale_env` Playwright kwarg (persists across all navigations including `/project/<uuid>` deep-links) + `FLOW_URL`'s `?hl=en` on initial load. Branded model names confirmed locale-stable. Four new `TestSelectorLocaleInvariance` tests + four `TestSelectImageModel` runtime tests. **R2V live e2e on non-EN still pending (owner gate — requires authenticated non-EN Chrome profile).**
 - [ ] **Model Context Protocol (MCP) Server.** (Backlog) Expose core gflow-cli tools via MCP for language-agnostic agentic access. Planned in [PREDICT.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PREDICT.md) / [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/SCENARIO.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PLAN.md).
-- [ ] **Prompt Expansion ("Creative Director" mode).** (Backlog) Add an option to expand prompts using Google's official 5-component formula via Gemini. Planned in [PREDICT.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-prompt-expansion/PREDICT.md) / [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-prompt-expansion/SCENARIO.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-prompt-expansion/PLAN.md).
+- [x] **Tools framework + Prompt Expansion ("Creative Director") — shipped → develop (PRs #210 + #211, 2026-06-28).** Prompt expansion evolved from the never-released `-e`/`--expand` flag into a TOML-defined **Tools framework**: `creative-director` is the first built-in tool, invoked uniformly via `--tool/-t <name>[:k=v]` on every generation command (`image t2i`/`i2i`/`batch`, `video t2v`/`i2v`/`r2v`/`chain`) or standalone via `gflow tools list/show/run`. The tool rewrites a terse prompt via Gemini's 5-component formula (`src/gflow_cli/tools/`, stdlib-urllib expander, never-fatal: missing key / 429-backoff / network / empty-clean all fall back to the original), with 15 domain styles and deterministic banned-keyword stripping. `operations.expanded_prompt` records original + submitted expansion (withheld under `history_prompts=redacted`); `metadata_json.tool` records `{name, version, model, params, config_hash}` provenance (minimized in redacted mode). Reuses `GFLOW_CLI_GEMINI_API_KEY`; `GFLOW_CLI_GEMINI_MODEL` overrides. MCP parity: `gflow_list_tools` + a `tools` array param per AGENTS.md §61. Docs: [TOOLS.md](file:///C:/development/github/gflow-cli/docs/TOOLS.md) + [PROMPT_EXPANSION.md](file:///C:/development/github/gflow-cli/docs/PROMPT_EXPANSION.md). Memory `[[prompt-expansion-feature]]`.
+  - **PR #210 (framework):** `tools/` package (spec/loader/registry/runtime/expander/banned/invocation), `creative-director.toml`, `gflow tools list/show/run`, `--tool` on t2i/t2v (single-prompt guard kept), MCP `gflow_list_tools` + `tools` param.
+  - **PR #211 (broaden surface):** `original_prompt`/`tool` carried on the request DTOs (`GenerateImageRequest`/`GenerateVideoRequest`/`BatchPromptItem`/`ChainLinkSpec`); recorder reads `request.original_prompt` (kwarg retired); `metadata_json.tool` recording; `--tool` wired into i2i/batch/i2v/r2v/chain; single-prompt guard removed. Silent-misrecord hazard resolved by carrying `original_prompt` on the DTO rather than re-threading a kwarg through each recorder method.
+  - **Expander robustness — DONE 2026-06-28 (PR #214).** Per-attempt timeout lowered 30s→20s and an overall `max_total_seconds` wall-clock budget (default 60s) added to `tools/expander.py` — retries stop once the budget is spent and each attempt's timeout is clamped to the remaining budget, so sustained 429s can no longer block ~120s before fallback. `tenacity` (a dep) was evaluated and **rejected**: it is built around re-raising after retries whereas the expander must never raise (fall back to the original), and the per-attempt structlog + total-budget logic is clearer as a hand-rolled loop with injectable `transport`/`sleep`/`clock` seams.
+  - **`expand_prompt` reconcile — DONE 2026-06-28 (PR #215).** The legacy `mcp/prompts.py` `expand_prompt` MCP prompt is **deprecated** in favor of the `creative-director` tool (client-visible `[DEPRECATED]` marker; kept functional; removal slated for a future major). See [PROMPT_EXPANSION § Relationship to expand_prompt](file:///C:/development/github/gflow-cli/docs/PROMPT_EXPANSION.md).
+  - **My Tools — DONE 2026-06-28 (PR #216).** User-authored TOMLs in `<GFLOW_CLI_HOME>/tools/*.toml` are loaded into the registry (override-a-builtin-with-warning; malformed fails loud).
+  - **Backlog — deferred by design:** the S3 `Tool.apply(ctx)→outcome` dispatch framework. The research doc gates it on a *second, non-prompt* tool (e.g. Mockup) — building it now with a single prompt-only implementer is the documented "premature uniformity (guessed contract)" anti-pattern.
 - [ ] **Integrated Filmmaking Studio, Flow Worker & MCP SSE Service.** (Backlog) Port google-flow-worker, construct a local FastAPI/React filmmaking studio dashboard, and support HTTP/SSE MCP. Planned in [DESIGN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/DESIGN.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/PLAN.md).
 - [x] **Issue #92: Google account identity persistence shipped 2026-05-28 (PR #110).** After every `gflow auth login`, both auth strategies write the verified email to `$GFLOW_CLI_HOME/profile_<name>/.gflow_account`. `ProfileMeta.google_account` surfaces it; `gflow auth list` and `gflow auth list --json` display it. First-login auto-rename: when no `--profile` flag was given and the only profile is named `default`, it is renamed to the email local-part. `profile_store.rename_profile()` primitive added. Zero-credit smoke test (`tests/smoke/test_profile_account_smoke.py`) ships with backfill path for pre-existing profiles. LLM council (9-dim) run; all must-fix items applied before merge. See `KNOWN_ISSUES.md` § Resolved for full detail.
 - [x] **`/gflow:pr-council-review` slash command shipped 2026-05-26 (PR #97).** Multi-dimensional LLM council for open PRs (4 baseline + 8 adaptive dimensions, mandatory memory-slug binding, draft-PR guard, YELLOW escape valve, live-verify gate). Validated on PR #93; self-audited by 3-agent meta-council surfacing 13 must-fix items applied before merge. See memory `[[llm-council-code-review-pr93]]`.

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/README.md

@@ -23,6 +23,7 @@ You pay for Google AI Ultra or Pro, you have Veo credits, and you run real batch
 
 - **Batch generation.** Loop prompts straight from the shell: `for p in $(cat prompts.txt); do gflow image t2i "$p"; done`. Image batching plus `gflow video t2v` / `i2v` / `r2v` all ship today.
 - **Consistent subjects.** `gflow character create` mints a Flow Character (face and body reference) so the same person appears from one generation to the next.
+- **Prompt tools.** `--tool creative-director` rewrites a terse prompt into a vivid one (Google's 5-component formula) before generating — on any command. Bring your own with [My Tools](docs/TOOLS.md).
 - **Pipelines.** Wire Veo into your content automation, AI-video stack, or batch experiments.
 - **Terminal-native.** After one `gflow auth login`, you stay in the shell. No clicking through dialogs.
 

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/docs/CONFIGURATION.md

@@ -27,6 +27,9 @@ $env:GFLOW_CLI_HOME = "D:\gflow-cli"                                # PowerShell
 ```
 
 See [AUTHENTICATION § Session storage](AUTHENTICATION.md#session-storage) for the full layout.
+`$GFLOW_CLI_HOME` also holds `config.toml`, the SQLite catalog (`gflow.db`), and — if you
+create it — a `tools/` directory of user-authored "My Tools" TOMLs
+(`<GFLOW_CLI_HOME>/tools/*.toml`, auto-loaded; see [TOOLS.md § My Tools](TOOLS.md)).
 
 ### `GFLOW_CLI_PROFILE`
 
@@ -112,11 +115,26 @@ Deep setup, verification, and security notes live in
 
 ### `GFLOW_CLI_GEMINI_API_KEY`
 
-**What:** API key for the official Veo 3.1 SDK.
-**Required when:** `GFLOW_CLI_PROVIDER=official`.
+**What:** Public Gemini API key. Used by the **`creative-director`** prompt tool
+(`--tool creative-director` / `gflow tools run creative-director`, see
+[TOOLS.md](TOOLS.md) and [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)) and, in future, by the
+official Veo 3.1 SDK.
+**Required when:** you apply the `creative-director` tool (via `--tool` on any generation
+command, or `gflow tools run`), or `GFLOW_CLI_PROVIDER=official`.
 **Default:** unset
+**Behavior when unset:** the tool is a no-op — gflow logs an `INFO` notice and generates
+from your original prompt (it never fails the run). API errors (rate limit, network) fall
+back the same way after a short exponential-backoff retry, bounded by an overall ~60s
+wall-clock budget per call.
 **Get one:** <https://aistudio.google.com/apikey>
 
+### `GFLOW_CLI_GEMINI_MODEL`
+
+**What:** Gemini model used by the `creative-director` prompt tool.
+**Default:** `gemini-2.5-flash`
+**Note:** Override to select a newer Flash revision without upgrading gflow-cli, e.g.
+`GFLOW_CLI_GEMINI_MODEL=gemini-2.5-flash-lite`.
+
 ### `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`
 
 **What:** Maximum time (seconds) that `gflow auth login` waits for the user to complete the Google sign-in flow in the browser.
@@ -179,6 +197,11 @@ Use this when you want the DB on a different volume, outside `GFLOW_CLI_HOME`, o
 
 **Default:** `store`
 
+**Tool provenance:** when a prompt tool (e.g. `creative-director`) rewrites a prompt, `store`
+mode also records the submitted `expanded_prompt` and a full `metadata_json.tool` descriptor;
+`redacted` withholds the expanded prompt and reduces the descriptor to
+`{name, version, params_hash, config_hash}`. See [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md).
+
 ```bash
 GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 ```

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/docs/INDEX.md

@@ -34,6 +34,9 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[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 |
+| **[docs/TOOLS.md](TOOLS.md)** | Tools framework: the `gflow tools list/show/run` group, the `--tool/-t` option on generation commands, the TOML tool schema, how a tool is defined, "My Tools" user-authored tools, MCP exposure + §61 parity | Working on `gflow_cli.tools`, adding a built-in or user tool, or wiring `--tool` into a command |
+| **[docs/MCP.md](MCP.md)** | MCP server: `gflow mcp run` (stdio) + `gflow serve` (HTTP/SSE), the tools/prompts/resources surface, CLI↔MCP §61 parity, security model, client setup | Configuring an MCP client, working on `gflow_cli.mcp`, or debugging the stdio/SSE transports |
+| **[docs/PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)** | The `creative-director` tool: 5-component formula, 15 domain styles, banned-keyword policy, Gemini endpoint + I/O, never-fatal contract, `expanded_prompt` + `metadata_json.tool` provenance/redaction, config | Using or debugging `--tool creative-director`, editing the tool TOML, or auditing recorded prompt provenance |
 | **[docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/DESIGN.md](superpowers/plans/2026-06-23-mcp-ui-worker-integration/DESIGN.md)** | Integrated local Filmmaking Studio Web UI, Flow Worker queue daemon, and MCP SSE server design spec (HLD/LLD) | Understanding the integrated HTTP/SSE daemon architecture |
 | **[docs/IMAGE_UPSCALE_RECON.md](IMAGE_UPSCALE_RECON.md)** | `gflow image upscale` wire protocol: `upsampleImage` endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action `IMAGE_GENERATION`, inline base64 response, 4K Ultra-gating, REST-is-dead proof | Working on `gflow image upscale`, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
 | **[docs/AGENT_UI_RECON.md](AGENT_UI_RECON.md)** | Agentic Flow UI cohort: classic-vs-agentic DOM signature, server-side + volatile (flapping) A/B gating (no client-readable flag), why `_exit_agent_mode` fails, runtime-DOM-detection recommendation | Touching `_exit_agent_mode` / composer mode-switch, diagnosing exit 23 selector drift, or understanding Flow's agentic-UI A/B (#183/#174) |
@@ -75,6 +78,8 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"How do I chain clips into one continuous video (initial-frame I2V)?"** → [USAGE § `gflow video chain`](USAGE.md#gflow-video-chain)
 **"How do I stitch existing clips into one extended .mp4 (credit-free, no ffmpeg)?"** → [USAGE § `gflow scene`](USAGE.md#gflow-scene)
 **"How do I create a reusable character (face + body) I can reuse across generations?"** → [USAGE § `gflow character`](USAGE.md#gflow-character) · design: [CHARACTER](CHARACTER.md)
+**"How do I turn a terse prompt into a vivid one before generating?"** → `--tool creative-director:style=cinema` on any generation command — see [PROMPT_EXPANSION](PROMPT_EXPANSION.md) · framework: [TOOLS](TOOLS.md)
+**"What tools are available and what styles do they support?"** → run `gflow tools list` / `gflow tools show creative-director` — see [TOOLS](TOOLS.md)
 **"What preset voices can a character use?"** → run `gflow character voices` — see [USAGE § `gflow character voices`](USAGE.md#gflow-character-voices)
 **"My batch died with exit code 3 (auth) — what now?"** → [USER_GUIDE § Journey 7](USER_GUIDE.md#journey-7--recovering-from-an-authexpirederror-mid-batch)
 **"Exit code 4 (rate-limit) or 5 (content-policy) — how do I recover?"** → [USER_GUIDE § Journey 12](USER_GUIDE.md#journey-12--recovering-from-contentpolicyerror-or-ratelimiterror)
@@ -113,7 +118,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout). Prior: [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc). Prior: [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.22.0/docs/LIVE_VERIFICATION_v0.22.0.md

@@ -0,0 +1,86 @@
+# Live Verification — v0.22.0
+
+Release theme: **Tools framework ("Creative Director")** — TOML-defined prompt tools, the
+`gflow tools` group, the uniform `--tool/-t` option across all generation commands, "My Tools"
+user-authored tools, MCP parity, and an expander wall-clock budget.
+
+This file follows the project's release-evidence convention (a `LIVE_VERIFICATION_vX.Y.Z.md` per
+release). It has two parts: **Pre-tag gates** (filled before signing) and **Post-tag evidence**
+(filled after the live owner-run).
+
+---
+
+## Pre-tag gates
+
+### Automated coverage (CI-green on the release tree)
+
+The entire feature set shipped via PRs #210/#211/#213 (framework + broaden + docs) and the
+v0.22.0 follow-ups #214/#215/#216, **each merged to `develop` with full CI green** on Python
+3.11 / 3.12 / 3.13 and **SonarCloud quality gate at zero**:
+
+| Surface | Coverage |
+|---|---|
+| `gflow tools list/show/run` | `tests/cli` + `tests/tools` |
+| `--tool/-t` on `image t2i/i2i/batch`, `video t2v/i2v/r2v/chain` | `tests/cli`, `tests/features` (BDD), `tests/tools/test_runtime.py` |
+| Tool schema / loader / registry | `tests/tools/test_spec.py`, `test_loader.py`, `test_registry.py` |
+| Banned-keyword stripping | `tests/tools/test_banned.py` |
+| Gemini expander (never-fatal, retries, **time budget**) | `tests/tools/test_expander.py` (incl. budget/timeout cases) |
+| Provenance (`expanded_prompt`, `metadata_json.tool`, redaction) | `tests/data` recorder tests |
+| MCP `gflow_list_tools` + `tools` array param + §61 parity | `tests/mcp/test_server.py` |
+| `expand_prompt` deprecation marker | `tests/mcp/test_server.py::test_expand_prompt_is_marked_deprecated` |
+| "My Tools" user-dir loader | `tests/tools/test_registry.py::TestMyToolsLoader` |
+
+Local gates on the release tree: `pyright src` 0 errors, `ruff check` / `ruff format --check`
+clean, `scripts/ci/check_repo_hygiene.py` clean, `scripts/ci/check_doc_links.py` all resolved.
+
+### Doc-review council
+
+Council verdict: **RED / YELLOW / GREEN** across the 3 auditors (completeness / cross-reference /
+drift). 1 RED finding (release-blocking) and the Tier-2 polish were **fixed in the release-prep
+commit**; drift auditor was GREEN. Findings + resolutions:
+
+- **Tier 1 (was blocking) — FIXED:** the canonical reference docs still documented the removed
+  `-e/--expand` flag and omitted the entire tools surface. Updated `docs/USAGE.md` (replaced the
+  `-e/--expand` option + section with `-t/--tool`; added a `gflow tools` command section) and
+  `docs/CONFIGURATION.md` (`GFLOW_CLI_GEMINI_API_KEY` / `_MODEL` now describe the `creative-director`
+  tool, not `--expand`; added the `<GFLOW_CLI_HOME>/tools/` My-Tools dir + redaction note).
+- **Tier 2 — FIXED:** the expander wall-clock budget was undocumented — added to
+  `CHANGELOG [0.22.0]`, `PROMPT_EXPANSION.md §6`, and `TOOLS.md §3`; added a README feature line;
+  fixed the stale "dormant" `load_user_tools` docstring in `tools/loader.py`.
+- **Tier 3 (deferred, cosmetic):** banned-keyword list ordering differs (set-equal, 13 terms);
+  the CLI-vs-MCP `tools list` field asymmetry (`requires_env`) could note it's deliberate.
+
+Post-fix gates re-run green: `check_doc_links` (23 files), `ruff`/`ruff format`, `pyright src` 0,
+`tests/tools`+`tests/mcp` 85 passed, repo-hygiene clean.
+
+### Live feature verification — ⏳ PENDING (owner-run)
+
+The credit/key-gated live e2e is **deferred to a post-tag owner run** and is **not** met at
+tag time. Reason: a true end-to-end check of `--tool creative-director` requires a real
+`GFLOW_CLI_GEMINI_API_KEY`, an authenticated Flow profile, and (for the generation half) Veo
+credits — none of which are available to the automated release agent. The tool path is
+**never-fatal by design** (a missing key / API fault degrades to the original prompt), so this
+does not risk a broken default install, but the live rewrite-and-record assertion below must
+still be exercised by the owner.
+
+Owner checklist (run after publish, then fill **Post-tag evidence**):
+
+1. `gflow tools list` shows `creative-director`; `gflow tools show creative-director` lists styles.
+2. `GFLOW_CLI_GEMINI_API_KEY=… gflow tools run creative-director "a cat on a couch" --style cinema --json`
+   → `was_expanded: true`, a vivid multi-sentence prompt, **no banned keywords** in output.
+3. A real generation with a tool, e.g.
+   `gflow image t2i "a fox in the snow" --tool creative-director:style=cinema` (image gen is
+   credit-free) → assert the catalog row records the **original** prompt in `prompt`, the
+   rewrite in `expanded_prompt`, and `metadata_json.tool = {name, version, model, params,
+   config_hash}` (`gflow data show <id> --json`).
+4. Redaction: repeat (3) with `GFLOW_CLI_HISTORY_PROMPTS=redacted` → `expanded_prompt` withheld;
+   `metadata_json.tool` reduced to `{name, version, params_hash, config_hash}`.
+5. "My Tools": drop a TOML in `<GFLOW_CLI_HOME>/tools/mytool.toml` → it appears in
+   `gflow tools list`; a same-named file overriding a builtin logs `tool_user_override`.
+
+---
+
+## Post-tag evidence
+
+_(fill after the owner live run: the 5-layer ledger — command, exit code, catalog row JSON,
+structlog events, and a user-confirmable artifact.)_

{gflow_cli-0.21.0 → gflow_cli-0.22.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,9 @@
 
 ## Current release
 
-**v0.17.0 — alpha.** **Cookie-store session verification.** `verify_flow_profile` (contributed by @3mora2, PR #168) verifies a Flow session directly from the Chrome cookie store via `browser_cookie3` + `httpx` — a fast path that skips launching a browser — with a marker-gated Playwright fallback for encrypted/locked stores (Windows DPAPI failures included) and retry/backoff on transient HTTP errors. Entity-attach `WireFormatError` failures (exit 7) now carry an issue-#174-aware remediation hint plus `entity_attach_context` drift telemetry. Live-verified 2026-06-12 ([evidence](LIVE_VERIFICATION_v0.17.0.md)). Carries forward v0.16.0 (locale-free picker include selectors #170, `gflow image upscale` #171) and v0.15.1 (Docker `/dev/shm` hardening, mid-workflow 401 detection).
+**v0.22.0 — alpha.** **Tools framework ("Creative Director").** A TOML-defined prompt-tool system: `creative-director` rewrites a terse prompt into a vivid one via Google's five-component formula (public Gemini API, never-fatal), with 15 category-gated domain styles and deterministic banned-keyword stripping. Invoke it via the new `gflow tools list/show/run` group or the uniform `-t`/`--tool` option on every generation command (`image t2i`/`i2i`/`batch`, `video t2v`/`i2v`/`r2v`/`chain`), replacing the never-released `-e/--expand`. History records the original prompt, the submitted `expanded_prompt`, and `metadata_json.tool` provenance (redaction-honoring). **"My Tools"**: user-authored TOMLs in `<GFLOW_CLI_HOME>/tools/*.toml` load automatically. MCP parity via `gflow_list_tools` + a `tools` array param; the legacy `expand_prompt` MCP prompt is deprecated. The Gemini expander gained an overall wall-clock budget. Carries forward v0.21.0 (MCP server over stdio + HTTP/SSE). Verification: [LIVE_VERIFICATION_v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (CI/automated complete; live owner-run pending).
 
-**Develop (unreleased, post-v0.17.0):** *(empty — develop is the staging branch for the next release).*
+**Develop (unreleased, post-v0.22.0):** *(empty — develop is the staging branch for the next release).*
 
 ## Milestone history
 
@@ -63,6 +63,11 @@
 | `gflow image upscale <mediaId> --scale 2k\|4k` — credit-free download-menu upscale, 4K Ultra-gated (#171) | ✅ done (v0.16.0) |
 | Cookie-store session verification fast path (`verify_flow_profile`, PR #168) + Playwright fallback | ✅ done (v0.17.0) |
 | Entity-attach exit-7 remediation hint + `entity_attach_context` drift telemetry (#174 interim) | ✅ done (v0.17.0) |
+| Agentic-UI exit-23 `UiSelectorDriftError` + `out_dir` wiring (#183) | ✅ done (v0.18.0) |
+| Patchright opt-in browser engine (`GFLOW_CLI_BROWSER_ENGINE=patchright`) | ✅ done (v0.19.0) |
+| Aspect-ratio overrides under Agentic & Classic cohorts + `GFLOW_CLI_PREFER_CLASSIC` (#193) | ✅ done (v0.20.0 / v0.20.1) |
+| MCP server (`gflow mcp run` stdio + `gflow serve` HTTP/SSE) + daemon/queue scaffolding | ✅ done (v0.21.0) |
+| Tools framework: `gflow tools` group + `--tool` + `creative-director` + "My Tools" + MCP parity | ✅ done (v0.22.0) |
 | `gflow video batch` (TSV manifest) on `ui_automation` | ⏳ Phase B |
 | Persistence layer (stay-mounted batch sessions across project boundaries) | ⏳ Phase B |
 | Provider abstraction for official Veo 3.1 API | ⏳ planned |