GloriousFlywheel Future Public Projection Strategy 2026-04-23

GloriousFlywheel Future Public Projection Strategy 2026-04-23

Snapshot date: 2026-04-23

Purpose

Define the future public product and docs projection for GloriousFlywheel after the square-one internal contract work.

This note is the execution artifact for TIN-459.

It answers:

  • what may become public later
  • what must stay internal by default
  • what must be rewritten versus generated
  • what gates must pass before any public release or visibility reversal

It does not publish anything.

Governing Decision

GloriousFlywheel remains internal-first.

The future public surface should be a projection from internal truth, not the mixed internal repo surface itself.

That means:

  • do not flip the internal repo public as the next step
  • do not publish docs/research/ or docs/superpowers/
  • do not publish live Tinyland topology, hostnames, IPs, tailnet names, or operator-only access instructions
  • do not publish aspirational platform claims until the internal live contract and public examples can reproduce them

Future Public Product Shape

The future public GloriousFlywheel story should be:

a FOSS cache-first runner/cache/control-plane substrate for teams that want self-hosted CI acceleration with explicit runner classes, cache roles, and forge adapters.

The public story can include:

  • Kubernetes + OpenTofu deployment model
  • GitHub ARC as the primary adapter
  • GitLab as bounded compatibility
  • Attic as Nix acceleration
  • Bazel remote cache as optional build acceleration
  • FlakeHub or another release surface as publication/discovery, not runtime authority
  • dashboard/operator UX as an internal control-plane component, with a clear warning if mutation authority is not forge-neutral yet
  • explicit non-goals and maturity levels for KVM, GPU, macOS, Forgejo, and managed-control-plane ideas

The public story must not imply:

  • Tinyland’s private honey deployment is the product
  • internal hostnames or endpoints are reusable by outsiders
  • the dashboard already owns forge-neutral mutation authority
  • all config/docs are generated from one canonical file
  • compatibility-era Bzlmod or overlay flows are the primary adoption path

Public Surface Package

The first safe public package should be intentionally small.

Include

Surface Public intent
product overview explain the cache-first runner platform and non-goals
architecture overview describe the four-layer model without live topology
quickstart deploy with sanitized placeholder domains and cluster names
GitHub ARC guide primary supported forge-adapter path
cache roles guide Attic, Bazel, FlakeHub/publication boundaries
runner classes guide baseline labels, additive lanes, and maturity levels
security model generic runner isolation, secret handling, and device-lane boundaries
module/config reference generated or sanitized reference for supported knobs
compatibility appendix bounded GitLab/Bzlmod/overlay story
public roadmap maturity levels and non-goals, not internal Linear or issue mirrors

Exclude

Surface Reason
docs/research/ internal planning and evidence archive
docs/superpowers/ agent-worker execution instructions
live cluster access docs internal topology and operator access detail
tailnet/MagicDNS/IP details internal access surface
Linear state and private planning internal product-management surface
orgwide enrollment census internal repo and adoption evidence
private downstream repo playbooks internal rollout material
emergency operator runbooks internal repair material unless heavily sanitized

Rewrite Versus Generate

Rewrite by hand from internal truth

These are narrative product surfaces. They should be intentionally rewritten, not mechanically copied:

  • product overview
  • public roadmap
  • adoption quickstart
  • architecture narrative
  • compatibility appendix
  • security and threat-model explanation

Reason: public readers need a coherent product story, not internal execution history.

Generate or validate from source

These should be generated or at least mechanically checked where possible:

  • OpenTofu module variable and output reference
  • example organization.yaml schema and sanitized examples
  • supported runner label matrix
  • composite-action input reference
  • environment-variable reference
  • release artifact list

Reason: these surfaces drift if they are maintained only as prose.

Never export directly

These should not be copied into a public projection:

  • internal research notes
  • internal runbooks with live topology
  • secret-adjacent auth and proxy details
  • issue-closeout logs and rollout evidence
  • repo-specific downstream migration notes

Export Mechanism Options

No single mechanism is decided yet.

Viable options:

Option Fit Risk
public docs package generated from an export manifest best first step requires export filter and scrub checks
separate public repository clean boundary requires sync discipline from internal truth
same repo made public later simplest mechanically unsafe until internal surfaces are moved or scrubbed
docs site only fastest communication path does not solve FOSS source publication by itself

Recommended next architecture:

  1. keep GloriousFlywheel internal
  2. create an explicit public-export manifest
  3. generate or assemble a sanitized public docs package from that manifest
  4. only later decide whether code joins that public package or remains internal while the public surface stays docs-first

Public Projection Gates

Do not publish or make the repo public until all of these gates pass.

Content gates

  • no docs/research/ or docs/superpowers/ content in the public package
  • no live Tailnet, MagicDNS, private IP, SSH, kubeconfig, or dashboard access details
  • no Tinyland-specific endpoint presented as an external default
  • no stale cache endpoint examples
  • no Linear-only or private GitHub issue references required to understand the product
  • no internal downstream repo names required for the onboarding story

Contract gates

  • public docs agree with the internal live contract
  • public quickstart uses sanitized example domains and cluster names
  • public cache docs separate Attic, Bazel, and publication/discovery roles
  • public runner docs separate baseline lanes from additive/proof lanes
  • public auth docs state what exists and what is not yet forge-neutral

Reproducibility gates

  • public quickstart has been run against a clean example config
  • links pass
  • examples pass syntax checks
  • generated references are reproducible from the export inputs
  • the public package has a documented update path back to internal truth

Security gates

  • secret scan passes on the export output
  • endpoint/IP scrub passes on the export output
  • threat model and security boundary docs are present
  • security reporting or responsible-disclosure guidance exists if code is published

First Public MVP

The first public MVP should be docs-first and conservative.

It should answer only:

  1. what GloriousFlywheel is
  2. what it can honestly deploy
  3. what runner/cache contracts it supports
  4. how a user can run a sanitized example
  5. what is explicitly not supported yet

It should not include:

  • Tinyland production topology
  • internal operator repair playbooks
  • orgwide adoption metrics
  • the full historical research archive
  • managed-control-plane claims

Public Maturity Labels

Use maturity labels instead of binary supported/unsupported claims:

Label Meaning
core primary documented path with reproducible public example
internal-proven real internally, but not safe or packaged for public users yet
compatibility operationally useful, but not the lead product path
proof bounded canary or demonstration, not a general promise
future product direction only

Initial likely classification:

  • GitHub ARC baseline runners: core once public example is reproducible
  • Attic acceleration: core once sanitized setup is reproducible
  • Bazel remote cache: core or internal-proven depending on external endpoint decision
  • GitLab runners: compatibility
  • KVM lane: internal-proven
  • GPU/WebGPU lane: proof or internal-proven
  • macOS lane: proof
  • Forgejo/Codeberg: future until a real adapter proof lands
  • managed control plane: future

Config Parity Strategy

The public package should not claim full config generation yet.

Truthful public claim:

  • organization.yaml defines important deployment/environment shape
  • generated references may be produced from schema and module metadata
  • some narrative docs are still intentionally written and reviewed by humans

Future work may strengthen this into a generated contract, but that is not the current platform truth.

Immediate Next Work After This Note

The next execution project should not be more broad cleanup.

It should create a concrete public-export plan:

  1. define the export manifest
  2. define scrub checks
  3. define generated reference inputs
  4. draft the docs-first public MVP package
  5. run it against a clean example deployment or explicit dry-run harness

GloriousFlywheel