docs: describe the actual CI gate topology (local-ci on push, hosted on tags)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SKaSE8U5cwN4ZGFwhJwxSY

Author: dmealing

.github/workflows/conformance.yml

@@ -7,6 +7,7 @@ name: conformance
 #   scripts/ci-local.sh --quick    # everything except the docker integration suite
 # The .githooks/pre-push hook also runs the TS build+typecheck gate locally, and the
 # cheap public-repo SECURITY gate (hygiene / leak-scan) still runs on every PR.
+# Push-to-main coverage now comes from local-ci.yml on the self-hosted runner.
 on:
   push:
     tags:

.github/workflows/integration-tests.yml

@@ -13,6 +13,7 @@ name: integration-tests
 #   scripts/ci-local.sh            # full local CI (this suite + conformance + drift)
 #   scripts/integration-test.sh <port>
 # The cheap public-repo SECURITY gate (hygiene / leak-scan) still runs on every PR.
+# Push-to-main coverage now comes from local-ci.yml on the self-hosted runner.
 
 on:
   push:

CLAUDE.md

@@ -66,8 +66,13 @@ bypasses branch protection. This hook closes that hole locally: when a push touc
 `server/typescript/` or `client/web/`, it runs the same `bun run --filter '*' build &&
 … typecheck` gate CI runs and **blocks the push when it is red** (~6s on a clean tree;
 skipped entirely for non-TS pushes). Bypass in an emergency with `git push --no-verify`
-or `SKIP_TS_TYPECHECK=1 git push`. The Java/C#/Python compile+conformance gates stay
-CI-only (still required on PRs via branch protection).
+or `SKIP_TS_TYPECHECK=1 git push`. The Java/C#/Python compile+conformance gates do NOT run on PRs (hosted CI runs
+them on release tags + manual dispatch only, for cost). Instead, every push to
+`main` triggers `local-ci.yml` on the maintainer's self-hosted runner: affected
+ports only (via `scripts/ci-affected-ports.sh`), parallel per-port jobs, each
+running `scripts/ci-local.sh --only <port> --strict-toolchains`; a nightly
+dispatch runs the full matrix. PRs get the leak-scan only — run
+`scripts/ci-local.sh --quick` locally before opening one.
 
 ## Monorepo layout
 

scripts/ci-local.sh

@@ -77,11 +77,10 @@ want() { # want <section> — true when the section should run
 PASS=(); FAIL=(); SKIP=()
 have() { command -v "$1" >/dev/null 2>&1; }
 
-# bun's installer exits 1 when an OPTIONAL native dep fails to build (e.g. the
-# ssh2/cpu-features chain) even though the workspace is fully usable — and an
-# immediate re-run exits 0. Retry once so fresh checkouts (the self-hosted CI
-# runner wipes its workdir every run) don't fail the gate on that flake; a
-# genuinely broken install still fails both attempts.
+# bun exits 1 when an OPTIONAL native dep fails its install script (the
+# ssh2/cpu-features chain needs node-gyp on the machine — `npm i -g node-gyp`
+# fixes it for good). Retry once as defense-in-depth for transient installer
+# flakes; a genuinely broken install still fails both attempts.
 bun_install() { bun install || bun install; }
 
 step() {  # step "<name>" <cmd...>