[ice-zeus]

Not ready for review yet: the linux job's native/updater checks fail on a compile defect on main (outside this PR's .github/** scope; the fix is in #7). Every other check, including the Linux desktop build, is green on the CI pool.

Outcome

.github/workflows/ci.yml runs the Tier-1 merge gate on ready pull requests (types opened, synchronize, reopened, ready_for_review; drafts skipped) and on pushes to main, with concurrency cancel-in-progress, only on the shared pool's self-hosted ci-heavy runners (no machine pinned) (no pull_request_target, only actions/checkout pinned by SHA).

• changes: path filter from the merge commit's diff.
• docs (every ready PR; the only check of a docs-only PR): git diff --check and freshness of tool/render_docs.py output.
• format and analyze: pinned Flutter 3.47.5 check, flutter pub get --enforce-lockfile, dart format --set-exit-if-changed on changed Dart files (the tree is not format-clean yet), flutter analyze --no-pub --fatal-infos --fatal-warnings.
• tests and changed-line coverage: flutter test --no-pub --coverage, the tool/update unittest under coverage.py, diff-cover 10.6.0 at 85% (90% for lib/update/, lib/proxy/system_proxy.dart, lib/data/store.dart, tool/update/, native/updater/**).
• android debug APKs (android/**, pubspec or the workflow): flutter build apk --debug --flavor direct and --flavor play.
• linux debug build and native/updater (linux/, native/updater/, pubspec or the workflow): cargo fmt/clippy/test (Rust 1.99.0), then (even if those fail, so one run reports both) a GTK 3/libsecret check and flutter build linux --debug.
• .github/ci/setup.sh installs Flutter, JDK 17.0.21+9, Android cmdline-tools 22.0 (+ platform 36, build-tools 36.0.0, NDK 28.2.13676358) and hashed Python tools (.github/ci/requirements.txt) into $CI_CACHE_DIR/proxy-app, verified by SHA-256 and reused; HOME, pub, Cargo and Gradle caches live there too; no sudo, no actions/cache.
• macOS/iOS builds, the Swift tunnel-proxy tests and Android emulator e2e stay on the pool Macs outside GitHub Actions.
• Also regenerates docs/readme.html, which was stale on main (README gained "Application updates" without a re-render); the new docs check caught it.

Documentation

The gate is documented in the workflow header comment. A CI section for docs/development.md follows in the docs area (outside this PR's .github/** scope).

Evidence

• Run https://github.com/shifter-io/proxy-app/actions/runs/40513487720 on head 932b07d: changes ✓, docs ✓, format and analyze ✓, tests and changed-line coverage ✓, android debug APKs ✓ (both flavors), linux debug build and native/updater ✗ only in "cargo fmt, clippy and test"; its GTK/libsecret check and flutter build linux --debug passed (✓ Built build/linux/x64/debug/bundle/shifter_app).
• The cargo failure: native/updater/src/lib.rs:36 calls VelopackLocator::get_root_dir, which velopack 1.2.161 compiles only on non-Linux targets, so the updater has never built on Linux (defect on main, fixed in CI-2 Build the desktop updater bridge on Linux #7). This PR is rebased on it once it merges and must then be fully green.
• Earlier run https://github.com/shifter-io/proxy-app/actions/runs/40500758577 (head 4b2c45f): tests 121 passed, 2 live tests skipped; tool/update 2 tests OK.
• Red proof (CI-BRIEF step 9b): throwaway PR [DO NOT MERGE] CI proof: deliberate failures #6 (closed unmerged), adding an unformatted, untested library with an unused local and a failing test, run https://github.com/shifter-io/proxy-app/actions/runs/40513496524. Each error failed in its own step: flutter test (121 passed, 1 failed: "ci canary fails on purpose", Expected 3, Actual 2); changed-line coverage ("lib/ci_canary.dart (0.0%): Missing lines 2,4-5", below 85%); dart format ("Changed lib/ci_canary.dart"); flutter analyze (unused_local_variable at lib/ci_canary.dart:3:9). docs and android passed; linux failed only on the same cargo defect.
• actionlint 1.7.12 and shellcheck: clean on 932b07d.

Boundary: n/a (app repository).