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

{gflow_cli-0.20.1 → 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.20.1 → 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.20.1 → gflow_cli-0.22.0}/.env.template

@@ -129,3 +129,14 @@
 # scripts/dev/capture_locale_invariants.py or to live-verify a non-EN
 # language end-to-end (see KNOWN_ISSUES § issue #24).
 # GFLOW_CLI_LOCALE=en-US
+
+# -----------------------------------------------------------------------------
+# Headless Daemon (gflow serve)
+# -----------------------------------------------------------------------------
+
+# API Token header for gflow serve authentication (required when binding to non-local interface, e.g. 0.0.0.0).
+# GFLOW_DAEMON_TOKEN=
+
+# Port for gflow serve. Default is 8000.
+# GFLOW_DAEMON_PORT=8000
+

{gflow_cli-0.20.1 → gflow_cli-0.22.0}/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
     name: Secret scan (gitleaks)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0  # full history so gitleaks can diff against base
 
@@ -25,6 +25,20 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  # ── Security gate: dependency CVE audit against locked deps ──────────────
+  deps-audit:
+    name: Dependency audit (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Audit locked dependencies for known CVEs
+        # Fails the build on any known advisory. Accept later via: pip-audit --ignore-vuln <GHSA-id>
+        run: |
+          uv export --frozen --format requirements-txt --no-emit-project > requirements-audit.txt
+          uvx pip-audit -r requirements-audit.txt
+
   # ── Main test matrix ──────────────────────────────────────────────────────
   test:
     runs-on: ubuntu-latest
@@ -32,7 +46,7 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -88,7 +102,7 @@ jobs:
         github.event.pull_request.head.repo.full_name == github.repository
       )
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0  # shallow clones break blame / new-code detection
 

{gflow_cli-0.20.1 → gflow_cli-0.22.0}/.github/workflows/governance-advisory.yml

@@ -19,7 +19,7 @@ jobs:
     name: Materiality + traceability (advisory)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # full history so `git diff origin/<base>..HEAD` resolves
 

{gflow_cli-0.20.1 → gflow_cli-0.22.0}/.github/workflows/governance-benchmark.yml

@@ -18,7 +18,7 @@ jobs:
     name: Materiality gate backtest
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # full history — the backtest replays every commit
 

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.20.1 → gflow_cli-0.22.0}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
       ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
       NODE_VERSION: '22'
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 

{gflow_cli-0.20.1 → 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
 
@@ -92,3 +95,7 @@ worktrees/
 
 # Understand Anything (local knowledge graph)
 .understand-anything/
+.worktrees
+
+# Subagent-driven-development scratch (ledger + task reports)
+.superpowers/

{gflow_cli-0.20.1 → 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
@@ -58,6 +59,7 @@ Or invoke the wrapper: `/gflow:check`.
 - 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–22, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`). 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).
+- **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_server.py`.
 
 ## PR instructions
 
@@ -80,7 +82,7 @@ The `skills/` directory ships installable agent skill docs in plain Markdown wit
 | `status` | [`skills/status/SKILL.md`](skills/status/SKILL.md) | Show current plan state, progress, and next unchecked task |
 | `pr-council-review` | [`skills/pr-council-review/SKILL.md`](skills/pr-council-review/SKILL.md) | Multi-dimensional PR council review |
 
-**Cursor / Aider / Codex / Gemini CLI:** paste or include the relevant `SKILL.md` in your system context.
+**Cursor / Aider / Codex / Gemini CLI (`agy`):** paste or include the relevant `SKILL.md` in your system context. Note: in the `agy` TUI prompt, custom slash commands (e.g. `/gflow:pr-council-review`) are blocked by the TUI's command parser. Type them as plain text without the leading slash (e.g. `gflow:pr-council-review`, `gflow:branch-review`, or `gflow:check`) to trigger the corresponding agent skill workflow.
 **Claude Code:** the `/gflow:` slash commands in `.claude/commands/gflow/` are auto-discovered when the project is open — no extra setup needed. To register a skill globally, copy the command file to `~/.claude/commands/`.
 **Custom agents:** fetch `skills/gflow-cli/SKILL.md` into your knowledge base before answering gflow questions.
 

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

@@ -7,6 +7,69 @@ 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
+
+- **MCP server** (`gflow mcp run`): a [Model Context Protocol](https://modelcontextprotocol.io) server over **stdio** that exposes gflow's image / video / data operations to MCP-aware agents (Claude Desktop, Cursor, VS Code) as JSON-RPC **tools, resources, and prompts**. Point the client at `gflow mcp run` (example config in `gflow mcp run --help` and [docs/MCP.md](docs/MCP.md)). `gflow mcp setup --target <claude-desktop|cursor|vscode>` is scaffolded for future auto-configuration.
+- **MCP over HTTP/SSE** (`gflow serve`): serves the same MCP server over Server-Sent Events — stream at `/sse`, POST messages to `/messages/`. Binds `127.0.0.1:8000` by default; non-loopback binds require `GFLOW_DAEMON_TOKEN`. Foundation for the forthcoming Gflow Studio Web UI and REST `/api/v1` surface.
+- **Daemon & generation-queue scaffolding** (internal foundation): a FastAPI lifespan daemon, a `FlowWorker` background processor, and a SQLite-backed generation queue (`QueueRepository` + migration `0007_queue`, swept to `failed` on restart). Lays the groundwork for queued asynchronous generation; not yet wired into a user command (`gflow serve` currently runs the MCP/SSE server only).
+
+### Fixed
+
+- **Security — `cryptography` advisory** ([GHSA-537c-gmf6-5ccf](https://github.com/advisories/GHSA-537c-gmf6-5ccf)): bumped the locked `cryptography` from 48.0.0 to 49.0.0 (transitive dependency).
+
+### Changed
+
+- **CI — dependency CVE gate**: added a `pip-audit` job that audits the locked dependency set on every PR and fails on known advisories.
+- **Code health**: SonarCloud cleanup sweep across the CLI, API, transport drivers, and movie/manifest layers (cognitive-complexity, duplicate-literal, and unused-argument refactors) with no behavioral change.
+
 ## [0.20.1] — 2026-06-16
 
 ### Fixed
@@ -1565,7 +1628,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.20.1...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
 [0.19.0]: https://github.com/ffroliva/gflow-cli/compare/v0.18.0...v0.19.0

{gflow_cli-0.20.1 → 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.20.1 → 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.22.0/GEMINI.md

@@ -0,0 +1,31 @@
+# GEMINI.md
+
+> Project memory hub for **Gemini CLI**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Gemini CLI, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Gemini-specific session protocol only.
+
+## What this project is
+
+`gflow-cli` is an unofficial Python CLI that drives [Google Flow](https://labs.google/fx/tools/flow) (Veo image-to-video, Imagen text-to-image) from the terminal by reverse-engineering Flow's private REST API. See [README.md](README.md) for the user-facing overview.
+
+## On every session start
+
+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 (type as plain text in the `agy` TUI prompt):
+   - 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`
+
+## Gemini-specific
+
+- Use specialized skills when relevant (e.g., `find-docs` for library research, `pr-council-review` for PR audits).
+- Maintain memory via the `mcp-mempalace` tool if available.
+- Prioritize **turn efficiency** and **high-signal output**.
+
+## Active phase
+
+- **Decoupled Daemon/Worker Plan:** The blueprint for the headless SSE Daemon, SQLite generation queue, and Tauri/React editor is scheduled in [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/PLAN.md) and [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/SCENARIO.md).
+- **Core Lesson (Retrospective):** Kept `gflow-cli` strictly headless (running Uvicorn and FastMCP over localhost HTTP/SSE). Bypassed browser context locks by serializing task writes in SQLite queue, allowing parallel client database reads via WAL mode.
+
+See [PLAN.md](PLAN.md) or type `gflow:status` for the current task. Type `gflow:plan <feature>` to create a new feature plan.