Pooled, cache-first build and runner substrate for local development and CI.

GloriousFlywheel is a working alpha implementation of:

• capability-class runner lanes
• Attic-backed Nix acceleration
• Bazel remote-cache acceleration
• narrow explicit Bazel REAPI proof lanes for selected target classes
• shared developer and CI contract surfaces
• operator and control-plane tooling

The source repo remains private because direct full-repo visibility is still blocked by internal planning/history exposure. The safe public-alpha route is the green fresh-history mirror seed generated by just public-alpha-export; directly flipping this private repo public still requires scrub, history rewrite, or explicit exposure acceptance.

• docs/: internal product, operator, architecture, and status docs
• public-docs/: conservative future public package projected from internal truth
• examples/: consumer-facing cache and runner attachment examples for the public alpha export
• docs/research/: internal planning and evidence notes

docs/ is not a polished public API. The public-alpha package is the smaller public-docs/ tree and its export/scrub tooling.

• honey is the only physical cluster target
• GitHub is the primary forge surface
• GitLab remains a compatibility path
• capability classes such as tinyland-nix, tinyland-docker, tinyland-dind, and bounded additive lanes such as tinyland-nix-heavy are the normal runner taxonomy
• repo identity is not runner taxonomy
• owner-specific GitHub App installs, tfvars, and private auth media belong in implementation overlays, not the core product stack
• local development and CI are meant to use the same shared substrate
• current main proves shared cache acceleration plus narrow target-scoped REAPI proofs for //app:build, //app:unit_tests, //:deployment_bundle, //docs-site:build, and the WAS-110 public-input handoff; it does not prove universal full remote offload for every developer workload
• operator access is private and tailnet-first
• environment-owned S3-compatible state is the live authority for the main stacks
• Attic and Bazel are acceleration layers, not publication surfaces
• FlakeHub is publication and discovery work, not runtime/bootstrap

GloriousFlywheel is not a repo-specific runner enrollment catalog. Repo-shaped runner labels are architectural debt, not the product direction.

• Internal Docs Index
• Future Public Docs Package
• Current State
• Public Alpha Reopen Readiness
• Infrastructure Quick Start
• Pilot Repo Guide
• Browser RBE Candidate Guide
• Justfile Commands

Repos that want to pilot GloriousFlywheel today should start with the cache-backed path, not the executor-backed proof lane:

• use shared capability-class runner labels such as tinyland-nix, tinyland-docker, or tinyland-dind
• bootstrap Nix through the shared composite actions or an equivalent repo-local wrapper
• require a real BAZEL_REMOTE_CACHE before claiming Bazel cache-backed execution
• pass --remote_cache="$BAZEL_REMOTE_CACHE" from a wrapper after cache preflight succeeds
• keep pull-request cache behavior read-only unless a trusted write policy is explicitly selected
• treat RBE as target-class scoped: use executor-backed mode only for targets in config/rbe-target-eligibility.json or for an explicit proof run that will update that manifest
• for browser-backed RBE candidates, use the declared browser runtime authority and disable Playwright/Puppeteer lifecycle browser downloads before asking for a forced executor proof

The public-export-safe starting point is the Pilot Repo Guide and the Pilot Workflow Template. Internal operators should pair them with Cache Integration, Bazel Remote Execution, and Bazel External Fetch Authority. For Vite/SvelteKit Playwright or Puppeteer proof work, also read Browser Runtime Authority.

Enter the repo through direnv allow or nix develop first. That devshell is the normal entrypoint for the shared dev+CI substrate contract, but it only attaches Bazel dogfood to the shared cache-backed path once the shell has a real BAZEL_REMOTE_CACHE value.

Normal developer usage is:

• enter the devshell with direnv allow or nix develop
• run just info and confirm whether Bazel is in shared-cache-backed or compatibility-local-only mode; the shell does not invent a shared cache endpoint on its own
• run just cache-contract when you need a non-networked explanation of the current cache attachment state
• use just bazel-build-cached for Bazel dogfood once just cache-contract-strict passes against a real shared cache endpoint
• use the executor-backed RBE path only for explicit proof or eligible target classes; target eligibility is tracked in config/rbe-target-eligibility.json
• use just check, just nix-build, and just app-test for routine repo validation
• treat raw local bazel build, raw local bazel test, bazelisk, and --config=ci as compatibility or debug paths only

Current main proves cache-backed local execution with shared cache acceleration and target-scoped executor-backed REAPI proofs. It does not prove universal full remote execution or remote-builder offload for every developer workload, so that boundary stays explicit.

just check
just nix-build
just app-test

The repo also validates the Nix dashboard derivation in CI with nix build .#runner-dashboard. Use just nix-check or just check-full when you explicitly need the heavier full-flake validation path.

• this source repo remains private while direct full-repo visibility is blocked by operator-only topology, planning material, and Git history
• public-docs/ is the conservative public-alpha entrypoint
• the generated public-docs references are enforced by just check-public-docs
• the scrubbed public-alpha mirror seed is enforced by just public-alpha-export-check and materialized by just public-alpha-export
• dogfood contract drift is enforced by just dogfood-contract-audit
• direct full-repo visibility is checked separately with just public-alpha-visibility-report; it is not the same as source dogfood health
• broad repo-level GitHub issues stay quiet by default; new repo work should be reopened intentionally when it needs issue tracking

Zlib