GloriousFlywheel Surface Inventory And Classification 2026-04-23

GloriousFlywheel Surface Inventory And Classification 2026-04-23

Snapshot date: 2026-04-23

Purpose

Provide the first concrete inventory pass after the repo-visibility decision.

This note does not define the future public contract. It classifies the current repo surface so later contract work can be deliberate instead of improvisational.

Repo visibility was changed to internal on 2026-04-23 before this inventory pass.

Classification Vocabulary

  • public-canonical candidate content that could plausibly survive into a future extracted public surface after sanitization and contract alignment
  • internal-operator content that is operationally useful but contains live topology, operator access, auth implementation detail, or other internal-only material
  • internal-planning execution notes, research, evidence, or agent-facing material that should not be part of a future product-facing docs surface
  • compatibility-legacy historical or compatibility material that may remain in the internal repo but should not lead the main product story
  • stale-or-conflicted content whose current claims disagree with other canonical docs or still point at old endpoints / old authority assumptions

High-Signal Surface Matrix

Surface Class Why Immediate action
docs/current-state.md public-canonical candidate best current public boundary page; now honest about zero open GitHub tracker debt and the month-1 closeout surface keep as one future public anchor, but align it to the coming internal live contract instead of letting it drift alone
docs/architecture/platform-layers.md public-canonical candidate already states the right platform shape: FOSS substrate, forge adapters, future managed control plane, compatibility kit preserve for future public projection
docs/architecture/multi-repo-layout.md public-canonical candidate clearly says this repo is the primary source of truth and overlay/GitLab context is historical compatibility preserve, but later remove internal-specific consumer examples if needed
docs/architecture/bzlmod-topology.md public-canonical candidate explains the compatibility-only attic-iac module name without making overlay the lead story preserve, but tie it to the repo-identity cleanup backlog
docs/compatibility-kit.md public-canonical candidate already relocates overlay compatibility to Jesssullivan/bzl-cross-repo and bounds what the kit covers preserve as the compatibility boundary
docs/reference/config-reference.md public-canonical candidate accurately states that config/organization.yaml is the central deployment config surface keep, but later pair with a stronger statement about what is and is not generated from it
docs/infrastructure/cluster-access.md internal-operator contains live API server, host IPs, MagicDNS service names, SSH examples, and operator access paths keep internal-only; do not project into public docs
docs/infrastructure/proxy-and-access.md internal-operator contains private host access and SOCKS proxy paths through live tailnet hosts keep internal-only
docs/infrastructure/quick-start.md internal-operator mixes real operator bootstrap, live API endpoint, backend authority specifics, and internal host-secret expectations split later into internal operator bootstrap versus sanitized public onboarding
docs/getting-started-guide.md internal-operator still assumes direct operator access to the real honey cluster and its private API keep internal-only until a public onboarding path exists
docs/infrastructure/customization-guide.md internal-operator documents private_api_server, magicdns_zone, and the live internal config shape keep internal-only
docs/dashboard/overview.md internal-operator documents real auth modes, request precedence, compatibility mutation paths, and unresolved mutation authority keep internal-only until a stable auth/control contract exists
docs/research/README.md + docs/research/* internal-planning the directory explicitly defines itself as the internal planning and evidence surface keep internal-only and exclude from any future public projection
docs/superpowers/plans/* internal-planning includes explicit agent-worker instructions and execution choreography keep internal-only and consider moving out of docs later
docs/infrastructure/overlay-creation.md compatibility-legacy still describes overlay creation and old namespace/config shapes for legacy consumers keep only as a compatibility reference, not primary onboarding
docs/architecture/forge-adapter-matrix.md compatibility-legacy useful model doc, but still ties GitLab compatibility to GitLab-managed state as if that is current adapter truth keep, but rewrite once the live contract is defined
docs/architecture/cache-and-state-roles.md stale-or-conflicted correctly describes cache roles, but still says current state backend is GitLab HTTP instead of S3-compatible on honey rewrite during live-contract consolidation
docs/architecture/deployment-contract.md stale-or-conflicted still declares all 4 stacks on GitLab HTTP state and old namespaces like attic-cache-dev rewrite or quarantine immediately
docs/runners/cache-integration.md stale-or-conflicted still points at attic-cache-dev and attic.dev-cluster.example.com rewrite against the internal live contract
docs/runners/self-service-enrollment.md stale-or-conflicted still teaches GitLab-group component flows and old Attic endpoint defaults as if they are current shared enrollment truth rewrite or demote to legacy compatibility guidance
docs/architecture/builder-contract.md stale-or-conflicted the product story is good, but the dev-machine example still points at https://attic.tinyland.dev rather than the current Attic contract keep, but fix against the live contract

Current Contract Drift

These are the highest-value contradictions the next contract pass must settle.

State authority

  • docs/current-state.md says the active stacks now use the environment-owned S3-compatible state path on honey.
  • docs/architecture/cache-and-state-roles.md still says the current backend is GitLab Managed Terraform State.
  • docs/architecture/deployment-contract.md still lists all four stacks on GitLab HTTP state.

This is the clearest current contradiction in the repo.

Attic endpoint and consumer contract

  • docs/architecture/cache-and-state-roles.md says Attic is https://nix-cache.tinyland.dev.
  • docs/architecture/builder-contract.md still tells dev machines to attic login gloriousflywheel https://attic.tinyland.dev.
  • docs/runners/cache-integration.md and docs/runners/self-service-enrollment.md still reference https://attic.dev-cluster.example.com.

The internal live contract must choose one real operator/developer-facing Attic surface and demote the others to historical notes if they still matter.

Bazel cache addressing

  • docs/infrastructure/cluster-access.md and docs/infrastructure/proxy-and-access.md expose the private tailnet gRPC endpoint bazel-cache-grpc.taila4c78d.ts.net:9092.
  • docs/runners/cache-integration.md still treats grpc://bazel-cache.attic-cache-dev.svc.cluster.local:9092 as the current canonical path.

That likely reflects an unresolved distinction between pod-internal, cluster-internal, and operator-visible addresses. The live contract needs to define the supported address per audience.

Auth and control-plane authority

docs/dashboard/overview.md documents:

  • GitLab OAuth
  • WebAuthn
  • Tailscale proxy-header auth
  • mTLS proxy-header auth

and also says there is still no GitHub-native or cluster-native mutation authority.

That is useful internal truth, but it is not yet a clean public control-plane story.

Configuration-Parity Finding

The repo does have a partial central source of truth:

  • docs/reference/config-reference.md defines config/organization.yaml as the central configuration surface
  • app/scripts/generate-environments.ts generates dashboard environment and app metadata from that config
  • scripts/validate-org-config.sh validates the baseline shape

That is real progress, but it is not full contract generation.

The live docs, endpoint surfaces, auth story, and cache/publication guidance are still hand-maintained and can drift independently from config/organization.yaml.

That means the future public projection should not be described as “generated from config” until more of the contract is actually derived from a single source of truth.

Immediate Program Implications

Milestone 1: Boundary and Visibility Decision

Status:

  • repo visibility decision is done
  • the repo now acts as the internal source of truth

Remaining Milestone 1 output:

  • one short boundary note that states what classes of material are never part of the future public surface

Milestone 2: Surface Inventory and Classification

This note is the first concrete pass.

Next inventory pass should:

  • expand the matrix beyond the highest-signal docs above
  • include scripts, workflows, and generated config surfaces
  • record an owner and disposition for each conflicting document

Milestone 3: Live Contract Consolidation

First contract bundle should settle:

  1. state authority
  2. Attic URL and audience-specific access mode
  3. Bazel cache addresses by audience
  4. auth and mutation-authority story
  5. internal versus public onboarding expectations
  1. Keep the repo internal while the classification and contract work runs.
  2. Open Linear issues under Milestone 2 and Milestone 3 rather than reopening broad GitHub tracker debt.
  3. Rewrite cache-and-state-roles.md, deployment-contract.md, cache-integration.md, and self-service-enrollment.md against one internal live contract instead of editing them independently.
  4. Decide whether docs/superpowers/ should remain under docs/ at all, even internally, or move to a clearly non-canonical internal execution surface.

GloriousFlywheel