gflow-cli 0.75.0__tar.gz → 0.76.0__tar.gz

{gflow_cli-0.75.0 → gflow_cli-0.76.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.75.0 → gflow_cli-0.76.0}/.github/dependabot.yml

@@ -88,6 +88,26 @@ updates:
           - "version-update:semver-minor"
           - "version-update:semver-patch"
 
+  # Docker — the base image in docker/Dockerfile (python:3.14-slim).
+  #
+  # This covers the FROM line and nothing else. Dependabot has no view into packages
+  # installed by a RUN, so `google-chrome-stable` is NOT tracked here: it is pulled
+  # unpinned from Google's apt repo, which keeps only the current build, and a rebuild
+  # is what picks up a newer Chrome. The gflow-cli version is pinned separately via
+  # `ARG GFLOW_VERSION` and gated by tests/test_dockerfile_version_pin.py, so between
+  # the three of them every input to the image has a named owner.
+  - package-ecosystem: "docker"
+    directory: "/docker"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:00"
+      timezone: "Europe/Lisbon"
+    open-pull-requests-limit: 3
+    # Kept in sync with .github/workflows/labels.yml — see the note above.
+    labels:
+      - "dependencies"
+
   # GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"

gflow_cli-0.76.0/.github/workflows/mcp-registry.yml

@@ -0,0 +1,70 @@
+name: MCP Registry
+
+# Publishes server.json to the Official MCP Registry — the listing that feeds the
+# downstream directories (PulseMCP ingests it; GitHub's MCP gallery is built on it).
+#
+# Ordering matters and is why this hangs off `release: published` rather than the
+# tag push. `mcp-publisher` proves namespace ownership by reading the `mcp-name:`
+# token out of the PUBLISHED PyPI README, and PyPI metadata is frozen per release —
+# so the wheel has to be up first. `release.yml` publishes to PyPI and only then
+# creates the GitHub Release, so by the time this fires the token is live.
+#
+# Auth is GitHub Actions OIDC. There is no PAT and no device-code flow: the runner
+# exchanges its own short-lived identity token for registry credentials, which is
+# why this needs `id-token: write` and nothing else.
+
+on:
+  release:
+    types: [published]
+  # Manual re-run, e.g. a release whose registry publish failed after PyPI
+  # succeeded. `validate` runs first either way, so a bad server.json stops
+  # before anything is sent.
+  workflow_dispatch:
+
+# Write scopes live at JOB level (Scorecard Token-Permissions: a workflow-level
+# write grant reaches every job, current and future).
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # OIDC exchange with registry.modelcontextprotocol.io
+    env:
+      # Pinned by version AND digest: this step runs in a job holding id-token
+      # write and publishes publicly under io.github.ffroliva, so a moved tag
+      # must not silently change the binary that does it.
+      MCP_PUBLISHER_VERSION: "1.8.1"
+      MCP_PUBLISHER_SHA256: "a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install mcp-publisher
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          archive="${RUNNER_TEMP}/mcp-publisher_linux_amd64.tar.gz"
+          gh release download "v${MCP_PUBLISHER_VERSION}" \
+            --repo modelcontextprotocol/registry \
+            --pattern 'mcp-publisher_linux_amd64.tar.gz' \
+            --output "${archive}" --clobber
+          echo "${MCP_PUBLISHER_SHA256}  ${archive}" | sha256sum -c -
+          tar -xzf "${archive}" -C "${RUNNER_TEMP}" mcp-publisher
+          "${RUNNER_TEMP}/mcp-publisher" --version
+          echo "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
+
+      - name: Validate server.json
+        # Never `init` here: it only writes a TEMPLATE server.json, refuses when a
+        # real one exists, and exits 1 — which would abort the run before login.
+        run: mcp-publisher validate
+
+      - name: Authenticate with the registry (GitHub Actions OIDC)
+        run: mcp-publisher login github-oidc
+
+      - name: Publish
+        run: mcp-publisher publish

{gflow_cli-0.75.0 → gflow_cli-0.76.0}/AGENTS.md

@@ -74,8 +74,8 @@ If you can help unblock a pure HTTP transport (especially for video generation,
 
 Run these gates in order before every commit:
 
-```powershell
-$env:PYTHONUTF8=1
+```bash
+export PYTHONUTF8=1          # Windows PowerShell: $env:PYTHONUTF8 = "1"
 uv run python scripts/ci/check_repo_hygiene.py
 uv run python scripts/ci/check_doc_links.py
 uv run python scripts/ci/check_website_docs_pii.py
@@ -108,7 +108,7 @@ the five other mirror axes), which no command here can check and no CI gate can
 
 - 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–38, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`, 37 `InsufficientCreditsError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping. Exit 33 is reserved outside that map: `gflow doctor` findings-present — a successful diagnosis, not an error class.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–39, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`, 37 `InsufficientCreditsError`, 39 `FlowAccessUnavailableError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping. Exit 33 is reserved outside that map: `gflow doctor` findings-present — a successful diagnosis, not an error class.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **YAGNI / least-code**: prefer the smallest change that works. No speculative abstractions (interface/factory with one implementation), no config or flags nobody sets, no dead constants/helpers, no reinventing the stdlib. Review carries this as its own lens — the **D14 over-engineering** dimension of [`pr-council-review`](skills/pr-council-review/SKILL.md) (baseline, always runs). Its rubric is portable; the `ponytail` plugin (see CONTRIBUTING) is an optional accelerant, not a dependency.
 - **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_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.
@@ -339,7 +339,7 @@ content in a vendor directory.
 **Codex CLI / desktop app:** install the repo's skills-only plugin from the repository root,
 then start a new session:
 
-```powershell
+```bash
 codex plugin marketplace add .
 codex plugin add gflow@gflow-cli
 ```

{gflow_cli-0.75.0 → gflow_cli-0.76.0}/CHANGELOG.md

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.76.0] — 2026-09-16
+
+### Fixed
+
+- **The containerised sign-in now works on Windows, and no longer points at a service that
+  does not exist.** `docker/docker-compose.yml` hard-coded the X11 socket at
+  `/tmp/.X11-unix` and told non-Linux users to "use the VNC service below instead" — there
+  is no VNC service; the file defines `login`, `gflow` and `serve`. On Windows 11 + WSL2 the
+  display is real but lives elsewhere: WSLg publishes a live `X0` socket at
+  `/mnt/wslg/.X11-unix` with `DISPLAY=:0`, while `/tmp/.X11-unix` inside that distro is an
+  empty directory, so the default mounted nothing and Chrome exited against a display that
+  was not there. The mount is now `${X11_SOCKET:-/tmp/.X11-unix}`, unchanged for Linux, and
+  `docker/README.md` documents the WSL invocation plus the two prerequisites that actually
+  bite (run it from inside WSL, and enable Docker's WSL integration for that distro).
+- **The container image no longer silently installs a stale gflow.** `docker/Dockerfile`
+  hardcoded `pip install gflow-cli==0.75.0` with nothing tying it to `pyproject.toml`, so
+  the next release would have left the image on the old version while
+  `docker/README.md`'s verification table went on quoting the new one. The version is now
+  an `ARG` gated by `tests/test_dockerfile_version_pin.py`. That gate also asserts the
+  ARG's **position**: declared above the Chrome layer it would invalidate ~1.6 GB of apt
+  cache on every version bump, so the ordering is a cache contract, not style. The base
+  image is now tracked by Dependabot (`docker` ecosystem); Chrome stays unpinned, with the
+  reason and the refresh command written down rather than left implicit.
+- **An account with no Flow access was told gflow's selectors had drifted, and asked to
+  file a frontend bug.** Google Flow needs an age-verified account in a supported region
+  on a Google AI Plus, Pro or Ultra plan (or a qualifying Workspace plan). An account
+  without one is served Flow's own "you don't have access" screen instead of the app, and
+  gflow had no route for that state, so the editor sweep reported the only thing it could
+  see: the settings trigger never appeared. Measured on a newly created free Google
+  account, 2026-09-15, as an **A/B through the same command** — the probe neutered, then
+  restored, on live Flow:
+
+  | | exit | class | what the user is told |
+  |---|---|---|---|
+  | before | 23 | `UiSelectorDriftError` | *"Google may have updated their frontend … file a bug at github.com/ffroliva/gflow-cli/issues"* — on `https://flow.google.com/unavailable`, after a 30 s wait, **with an incident bundle containing a screenshot of the account's own page** for the user to attach |
+  | after | 39 | `FlowAccessUnavailableError` | *"This Google account cannot reach Flow"*, naming the subscription and linking Google's eligibility page |
+
+  The guard goes in `raise_if_known_landing()`, already the single chokepoint for "we
+  landed somewhere unexpected" and shared by all three raise sites (the labs gallery
+  sweep, the labs prompt-box sweep, and the migrated composer's `ensure_editor`), so every
+  command that drives the Flow editor is covered by the one change. It now probes the DOM
+  before it reads the URL. Verified live at $0 on that account: `ui_driver.known_landing
+  kind=unavailable at=migrated.ensure_editor`, exit 39, nothing submitted.
+
+  Detection is by Angular component, not by path or status code, because the spike
+  ([`2026-09-15-unentitled-account-signal`](docs/superpowers/spikes/2026-09-15-unentitled-account-signal.md))
+  pre-registered four candidate signals and refuted all four. There is no entitlement field
+  on the session wire; `flow.google.com/` answers **HTTP 200** and performs the hop
+  client-side, so there is no 3xx to key on; and the path is not stable — `/unavailable`
+  and `/u/8/unavailable` were both observed, the second carrying Google's account-index
+  segment, which gflow does not parse anywhere. What is stable is Flow's own
+  `<flow-pinhole-unavailable-screen>`, rendered inside `aisandbox-root`, and unlike the
+  screen's prose it is locale-invariant by construction (AGENTS.md Tier 1). The probe is
+  total: a page that cannot be queried, or a locator that raises, reports "not seen" rather
+  than displacing the caller's own diagnosis.
+
+  **What this does not fix, and why — measured, not assumed.** The same account run
+  *without* `--project` never reaches the editor at all: it takes the labs REST arm and
+  dies at `labs.google/fx/api/trpc/project.createProject` with **HTTP 401**, which is still
+  reported as `AuthExpiredError` (exit 3) telling the user to log in again. `gflow auth
+  login` (exit 8) and `gflow auth status` (exit 1) are wrong in the same way. All three read
+  an oracle that cannot answer the question: `labs.google/fx/api/auth/session` returns 200
+  with an empty `user` for an abandoned sign-in *and* for an account with no entitlement,
+  and a REST 401 looks identical to an expired session. The discriminator exists only in
+  the DOM, and on the login path Chrome has already closed by the time the verdict runs, so
+  there is no page left to ask. Routing those means a browser probe on the auth path — a
+  separate change, on a surface `AGENTS.md` gates behind its own spike. (`gflow credits
+  user` exit 3 on that account is [#795](https://github.com/ffroliva/gflow-cli/issues/795),
+  a different real bug. `gflow project list` returning `{"projects": [], "total": 0}` was
+  never wrong — it lists the local SQLite catalog and never contacts Flow.)
+
+- **An MCP agent's `project_name` is finally used.** `gflow_generate_image` and
+  `gflow_generate_video` accept a `project_name` and document it as the title for a freshly
+  created Flow project, but the worker read a different key (`project_title`) that nothing in
+  the repository has ever written. Every supplied name was silently dropped and each new
+  project was created as the hardcoded fallback `gflow-cli images` instead. Dead since the
+  parameter shipped on 2026-07-26 — the daemon's read predated it by four days, and the
+  feature wired up a new key rather than the one already being read. The CLI was unaffected.
+
+### Added
+
+- **The Official MCP Registry listing now publishes itself.** A new `MCP Registry` workflow runs
+  on `release: published` — after `release.yml` has uploaded the wheel, which matters because
+  `mcp-publisher` proves namespace ownership by reading the `mcp-name:` token out of the
+  *published* PyPI README. It authenticates with **GitHub Actions OIDC**, so no personal access
+  token is created, stored or handed to the registry, and the `mcp-publisher` download is pinned
+  by version *and* sha256 since that job holds `id-token: write`. `workflow_dispatch` is there
+  for a re-run when a release's PyPI upload succeeded but the registry publish did not. Registry
+  listings feed the downstream directories: PulseMCP ingests it and GitHub's MCP gallery is built
+  on it.
+- **A gate for the MCP→worker payload-key round trip (#628).** `tests/mcp/test_cli_parity.py`
+  checks parity at the command and option level; neither can see the queue payload, where a
+  key written under one name and read under another type-checks, lints, passes every test and
+  does nothing at runtime. The new `tests/mcp/test_payload_key_round_trip.py` extracts the keys
+  `mcp/tools.py` writes and the keys anything under `worker/` reads, and fails on any written
+  key the worker never reads. It found the `project_name` defect above on its first run. The
+  extractors carry their own tests against synthetic sources, so the gate is proven able to go
+  red rather than merely observed green (precedent: a dead `output` param the queue never read,
+  found by hand in a v0.48.0 pre-release audit, #495).
+
 ## [0.75.0] — 2026-09-15
 
 ### Added
@@ -5101,7 +5201,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.75.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.76.0...HEAD
+[0.76.0]: https://github.com/ffroliva/gflow-cli/compare/v0.75.0...v0.76.0
 [0.75.0]: https://github.com/ffroliva/gflow-cli/compare/v0.74.0...v0.75.0
 [0.74.0]: https://github.com/ffroliva/gflow-cli/compare/v0.73.2...v0.74.0
 [0.73.2]: https://github.com/ffroliva/gflow-cli/compare/v0.73.1...v0.73.2

{gflow_cli-0.75.0 → gflow_cli-0.76.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.75.0
+Version: 0.76.0
 Summary: CLI and MCP server for Google Flow — drive Veo text-to-video, image-to-video and Imagen image generation from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Documentation, https://ffroliva.github.io/gflow-cli/
@@ -102,6 +102,7 @@ Description-Content-Type: text/markdown
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_gflow-cli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ffroliva_gflow-cli)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_gflow-cli&metric=coverage)](https://sonarcloud.io/component_measures?id=ffroliva_gflow-cli&metric=coverage)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ffroliva/gflow-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/ffroliva/gflow-cli)
+[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/ffroliva/gflow-cli)
 
 <!-- Gold sponsors appear here: filled by scripts/ci/update_sponsors.py, empty until there is one. -->
 <!-- sponsors-gold:start -->
@@ -189,6 +190,7 @@ Reproduce the recording with [`scripts/record_demo.ps1`](scripts/record_demo.ps1
 | 🎭 **Characters** | [Characters](docs/CHARACTER.md), reusable subjects (`gflow character`) |
 | 🤖 **Agentic & automation** | [Instructions](docs/INSTRUCTIONS.md) (`gflow instructions`, persistent brief cards) · [Movie](docs/MOVIE.md) (`gflow movie`, multi-scene manifests) · [Tools](docs/TOOLS.md) (`--tool`, prompt rewriting) · [MCP server](docs/MCP.md) (`gflow mcp run` / `gflow serve`) |
 | 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
+| 📣 **Where to install from** | [Marketplaces](docs/MARKETPLACES.md) (every channel and what each actually delivers) · [Container](docs/CONTAINER.md) (why the image introspects but cannot generate) |
 | 🏗️ **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) |

{gflow_cli-0.75.0 → gflow_cli-0.76.0}/README.md

@@ -16,6 +16,7 @@
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_gflow-cli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ffroliva_gflow-cli)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ffroliva_gflow-cli&metric=coverage)](https://sonarcloud.io/component_measures?id=ffroliva_gflow-cli&metric=coverage)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ffroliva/gflow-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/ffroliva/gflow-cli)
+[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/ffroliva/gflow-cli)
 
 <!-- Gold sponsors appear here: filled by scripts/ci/update_sponsors.py, empty until there is one. -->
 <!-- sponsors-gold:start -->
@@ -103,6 +104,7 @@ Reproduce the recording with [`scripts/record_demo.ps1`](scripts/record_demo.ps1
 | 🎭 **Characters** | [Characters](docs/CHARACTER.md), reusable subjects (`gflow character`) |
 | 🤖 **Agentic & automation** | [Instructions](docs/INSTRUCTIONS.md) (`gflow instructions`, persistent brief cards) · [Movie](docs/MOVIE.md) (`gflow movie`, multi-scene manifests) · [Tools](docs/TOOLS.md) (`--tool`, prompt rewriting) · [MCP server](docs/MCP.md) (`gflow mcp run` / `gflow serve`) |
 | 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
+| 📣 **Where to install from** | [Marketplaces](docs/MARKETPLACES.md) (every channel and what each actually delivers) · [Container](docs/CONTAINER.md) (why the image introspects but cannot generate) |
 | 🏗️ **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) |

gflow_cli-0.76.0/docker/Dockerfile

@@ -0,0 +1,53 @@
+# Spike image v2: REAL Google Chrome, not Playwright's bundled Chromium.
+#
+# gflow's own gate (browser_manager.is_playwright_chrome_channel_available) accepts
+# exactly one Linux path for channel="chrome": /opt/google/chrome/chrome. That is where
+# the google-chrome-stable .deb installs, so this image satisfies gflow's detector and
+# not merely Playwright's.
+# 3.14, not 3.11. 3.11 is only the project's requires-python FLOOR — a reason for the
+# minimum SUPPORTED version, not for a runtime image.
+#
+# CI's matrix is ["3.11","3.12","3.13"], so 3.14 is not covered by the suite. That matters
+# less here than it looks: a container pins its interpreter, so this is deterministic
+# rather than an ambient version that might surprise someone. The gap is closed by
+# verifying the image's actual runtime contract below rather than by staying on an older
+# interpreter — see docker/README.md § "Verified on this image".
+FROM python:3.14-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    GFLOW_CLI_UPDATE_CHECK=false \
+    GFLOW_CLI_HOME=/data/gflow
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      xvfb xauth ca-certificates curl gnupg \
+ && curl -fsSL https://dl.google.com/linux/linux_signing_key.pub \
+      | gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg \
+ && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main" \
+      > /etc/apt/sources.list.d/google-chrome.list \
+ && apt-get update && apt-get install -y --no-install-recommends google-chrome-stable \
+ && rm -rf /var/lib/apt/lists/*
+
+# The version lives in an ARG so a bump is a one-line change (or `--build-arg`), and
+# `tests/test_dockerfile_version_pin.py` fails when this default drifts from
+# pyproject.toml — otherwise the image silently keeps installing an old release while
+# docker/README.md goes on claiming the new one was verified.
+#
+# Declared HERE rather than beside FROM, and the placement is load-bearing. Measured
+# 2026-09-15 with an A/B on a throwaway image, using a unique marker so no stale cache
+# entry could match:
+#
+#   ARG after  the expensive layer -> that layer CACHED on a version bump
+#   ARG before the expensive layer -> that layer REBUILT
+#
+# Chrome above is most of this image's ~1.6 GB, so the wrong placement would turn every
+# gflow bump into a full Chrome reinstall. Keep this ARG below the apt layer.
+#
+# Deliberately NOT pinned: google-chrome-stable. Chrome's apt repo keeps only the current
+# build, so a pinned version stops resolving within weeks. The trade-off is that this
+# layer caches indefinitely and a rebuild is what picks up a newer Chrome.
+ARG GFLOW_VERSION=0.76.0
+RUN pip install --no-cache-dir "gflow-cli==${GFLOW_VERSION}"
+
+VOLUME ["/data"]
+WORKDIR /data
+CMD ["gflow", "--help"]

gflow_cli-0.76.0/docker/Dockerfile.test

@@ -0,0 +1,17 @@
+# Runs gflow's OWN offline suite inside the container, on the image's interpreter.
+# This is what turns "CI does not test 3.14" from a caveat into a measurement.
+FROM python:3.14-slim
+ENV PYTHONUNBUFFERED=1 PYTHONUTF8=1 GFLOW_CLI_UPDATE_CHECK=false UV_LINK_MODE=copy
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      xvfb xauth ca-certificates curl gnupg git \
+ && curl -fsSL https://dl.google.com/linux/linux_signing_key.pub \
+      | gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg \
+ && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main" \
+      > /etc/apt/sources.list.d/google-chrome.list \
+ && apt-get update && apt-get install -y --no-install-recommends google-chrome-stable \
+ && rm -rf /var/lib/apt/lists/*
+RUN curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh
+WORKDIR /app
+COPY . /app
+RUN uv sync --frozen 2>/dev/null || uv sync
+CMD ["uv","run","python","-m","pytest","-q","--no-cov","-p","no:cacheprovider"]

gflow_cli-0.76.0/docker/README.md

@@ -0,0 +1,215 @@
+# Running gflow-cli in a container
+
+**Status: measured, partially.** The plumbing works and the browser presents clean. The one-time
+Google sign-in inside a container has **not** been run, and neither has a generation. Evidence and
+exact readings: [`docs/superpowers/spikes/2026-09-15-container-transport-viability.md`](../docs/superpowers/spikes/2026-09-15-container-transport-viability.md).
+
+Do not read this as "containerised gflow is supported". Read it as "here is the protocol, here is
+precisely how far it has been verified, and here is what is left to try".
+
+## The shape
+
+**The container is disposable. The volume is not.** Everything that identifies you — the Chrome
+profile, `GFLOW_CLI_HOME`, the SQLite catalog — lives in the named `gflow-auth` volume, so the
+image can be rebuilt or upgraded without signing in again.
+
+## Two things that are not optional
+
+**Real Google Chrome, not Chromium.** `browser_manager.is_playwright_chrome_channel_available()`
+accepts exactly one Linux path for `channel="chrome"`: `/opt/google/chrome/chrome`. That is where
+the `google-chrome-stable` .deb installs. A distro Chromium does **not** satisfy it, and
+generation needs a real-Chrome profile.
+
+**`xauth` alongside `xvfb`.** `xvfb-run` fails with `xauth command not found` without it. This
+cost the spike an arm.
+
+## Xvfb is not a headless workaround
+
+Xvfb is a real X server with no attached monitor. Chrome runs genuinely **headed** against it.
+That is categorically different from Chrome's `--headless` mode, which is what Google's auth and
+reCAPTCHA stack rejects. Measured inside the container with gflow's own launch arguments:
+
+```
+REAL CHROME launched   : 153.0.8010.36
+navigator.webdriver    : None
+headless UA marker?    : False
+```
+
+## Use
+
+```bash
+# 1. Build
+docker compose build
+
+# 2. Sign in ONCE, into the volume. This is the only step a headless box cannot do —
+#    it needs a real display. See "Where the display comes from" below for Windows.
+xhost +local: && docker compose run --rm login
+
+# 3. Everything else runs headed under Xvfb against that volume
+docker compose run --rm gflow                      # gflow auth status
+docker compose run --rm gflow gflow credits user   # read-only, $0
+
+# 4. The MCP server, for an agent on the host
+export GFLOW_CLI_DAEMON_TOKEN=$(openssl rand -hex 32)
+docker compose up serve
+```
+
+## Where the display comes from
+
+Step 2 is the only step that needs a screen you can see, and the socket is not in the
+same place on every host. The `login` service mounts `${X11_SOCKET:-/tmp/.X11-unix}`,
+so the default suits Linux and everything else sets one variable.
+
+| Host | Command |
+|---|---|
+| Linux | `xhost +local: && docker compose run --rm login` |
+| Windows (WSL2 + WSLg) | run **from inside WSL**: `X11_SOCKET=/mnt/wslg/.X11-unix docker compose run --rm login` |
+| macOS | needs XQuartz; not verified here |
+
+**Why Windows needs the override.** Measured on Windows 11 + WSL2 (Ubuntu), 2026-09-15:
+WSLg publishes a live `X0` socket at `/mnt/wslg/.X11-unix`, and `DISPLAY` is already `:0`.
+But `/tmp/.X11-unix` **inside that same distro is an empty directory** — so the Linux
+default mounts nothing useful and Chrome exits immediately against a display that is not
+there. The variable is the difference between working and a confusing failure.
+
+Two things to check before blaming the compose file:
+
+- Run it **from inside WSL**, not Git Bash or PowerShell. On the Windows side
+  `/tmp/.X11-unix` does not exist at all, and Git Bash will additionally rewrite the path
+  (`/mnt/wslg/...` becomes `C:/Program Files/Git/mnt/wslg/...`).
+- Docker's **WSL integration must be on** for that distro — Docker Desktop → Settings →
+  Resources → WSL Integration. Without it the `docker` CLI inside WSL cannot reach the
+  daemon at all: `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`.
+
+## Rebuilding is cheap, and which layer moves is deliberate
+
+The image is two layers that matter, in this order:
+
+1. **Chrome + Xvfb** via `apt-get` — most of the ~1.6 GB, and the slow one.
+2. **`pip install gflow-cli==${GFLOW_VERSION}`** — small and fast.
+
+Because the expensive layer comes first, bumping the gflow version reuses it from cache
+and only the last layer rebuilds. A version bump is seconds, not minutes.
+
+That property is fragile in one specific way: **`ARG GFLOW_VERSION` must stay below the
+apt layer.** An ARG declared before an expensive layer invalidates it whenever the value
+changes. Measured 2026-09-15 on a throwaway image, with a unique marker so no stale cache
+entry could match:
+
+| `ARG` placement | expensive layer on a version bump |
+|---|---|
+| after it | `CACHED` |
+| before it | rebuilt |
+
+`tests/test_dockerfile_version_pin.py` asserts the ordering, so the cache contract cannot
+be undone by a tidy-up that moves the ARG next to `FROM`.
+
+### Who owns each input
+
+| Input | Pinned by | Updated by |
+|---|---|---|
+| `python:3.14-slim` base | the `FROM` line | Dependabot (`docker` ecosystem, `/docker`, weekly) |
+| `gflow-cli` | `ARG GFLOW_VERSION` | a release, gated by `tests/test_dockerfile_version_pin.py` |
+| `google-chrome-stable` | not pinned | a rebuild |
+
+Chrome is the deliberate gap. Google's apt repo keeps only the current build, so a pinned
+version stops resolving within weeks — and Dependabot cannot see packages installed by a
+`RUN` in any case. The consequence is worth stating plainly: **that layer caches
+indefinitely, so an image rebuilt from a warm cache keeps whatever Chrome it first
+installed.** `docker compose build --no-cache` (or pruning the cache) is what refreshes it.
+
+## `serve` refuses to start without a token — on purpose
+
+`docker compose config` **fails** when `GFLOW_CLI_DAEMON_TOKEN` is unset:
+
+```
+required variable GFLOW_CLI_DAEMON_TOKEN is missing a value: set a token before exposing this
+```
+
+That is the intended behaviour, not a bug to fix. Since v0.75.0 `gflow serve` verifies the token
+on **every** request; a daemon exposed without one hands every tool to any local caller. The port
+is published to `127.0.0.1` only for the same reason.
+
+## Verified on this image
+
+CI's matrix is `["3.11","3.12","3.13"]`, so the 3.14 base is not covered by the test suite.
+A container pins its interpreter, so this is deterministic rather than an ambient version that
+could surprise someone — and the gap is closed by verifying the image's runtime contract directly
+rather than by staying on an older interpreter:
+
+```
+python           : 3.14.7
+gflow_cli        : 0.75.0
+chrome channel   : True          (is_playwright_chrome_channel_available)
+chrome available : True          (is_chrome_available)
+initialize       : OK, server "gflow-cli"
+tools/list       : OK, 15 tools
+```
+
+Re-run that after any base-image bump. If it stops holding, the interpreter is the first suspect.
+
+> **Measured on the 0.75.0 image, not re-measured for 0.76.0.** The numbers above and in the
+> table below are a record of a run, so they are left as they were rather than edited to match
+> the current version — a quoted measurement that tracks `pyproject.toml` is not a measurement.
+> `ARG GFLOW_VERSION` *is* gated against the repo version by
+> `tests/test_dockerfile_version_pin.py`, so the image installs 0.76.0; what is unverified is
+> that the runtime contract still holds on it. Re-running the block above on a WSL-integrated
+> Docker host is what would settle it.
+
+## Benchmark — measured 2026-09-15
+
+Reproduce with `docker/Dockerfile.test` (copy `dockerignore.example` to `.dockerignore` at the
+repo root first). All figures from this machine; treat them as shape, not as a spec.
+
+| Metric | Result |
+|---|---|
+| Runtime image (real Chrome + Xvfb) | **1.65 GB** |
+| Test image (repo + dev deps, no Chrome) | **714 MB** |
+| Cold container -> `gflow --version` | **1475 / 1516 / 1511 ms** |
+| Cold container -> MCP `initialize` + `tools/list` | **2228 / 2406 / 2495 ms** |
+| `uv sync` during build | **14.8 s** |
+| gflow's offline suite, **on Python 3.14** | **4379 passed, 28 skipped** in **6m08s** |
+
+The MCP figure is the one that matters for agents: roughly **2.3 s from cold container to a usable
+tool list**. A long-lived `serve` pays that once; a one-shot `docker run` pays it every call.
+
+**The suite result is the point of the 3.14 base.** CI's matrix is `["3.11","3.12","3.13"]`, so
+this is the first time gflow's tests have run on 3.14 at all — which is what makes the interpreter
+choice a measurement rather than a preference.
+
+### Two tests cannot pass in a container built from a git WORKTREE
+
+`test_real_tree_passes_root_doc_check` and `test_the_generator_ships_only_what_git_tracks` both
+shell out to `git ls-files` to introspect **the repository**. In a worktree, `.git` is a 71-byte
+*pointer file*:
+
+```
+gitdir: C:/development/github/gflow-cli/.git/worktrees/container-spike
+```
+
+Docker copies the pointer faithfully, and inside the container it dangles:
+
+```
+fatal: not a git repository: /app/C:/development/github/gflow-cli/.git/worktrees/container-spike
+```
+
+Both then fail with `CalledProcessError … exit status 128`. **This is the build context, not the
+interpreter** — they test repo state, not runtime behaviour. Build from the main checkout (where
+`.git` is a real directory) and they have a repo to query. Adding `.git` to the context does *not*
+fix it on its own; that was tried and the failures were identical.
+
+## What is verified, and what is not
+
+| | |
+|---|---|
+| `gflow` runs in the container | ✅ measured — `gflow, version 0.75.0` |
+| Real Chrome at gflow's required path | ✅ measured — all three detectors return True |
+| Headed Chrome launches and browses | ✅ measured — Chrome 153, real page title |
+| No automation markers | ✅ measured — `navigator.webdriver` is `None` |
+| One-time Google sign-in in a container | ❌ **not run** |
+| Flow accepts the session; generation works | ❌ **not run** — a clean fingerprint is necessary, not sufficient |
+| Windows profile mounted into Linux | ❌ **not run** — expected to fail on DPAPI cookie decryption, which would be a portability limit, not anti-automation |
+
+If you run the sign-in arm, please report what happened on
+[#822](https://github.com/ffroliva/gflow-cli/issues/822) either way. A failure is as useful as a
+success, provided it names what it observed.