railiance-bootstrap/SCOPE.md

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

---

One-liner

The Railiance bootstrap path — turning a single bare virtual machine into a working Railiance, then handing off to the ordinary layers.

---

Core Idea

Every Railiance layer describes how to operate a system that already exists. S1 converges a substrate, S2 runs a cluster on it, S3 provides shared services. None of them owns the first step: you have one virtual machine and an intention — now what?

This repo owns that step. It sequences the layers into a runnable path from nothing to a working Railiance, and then gets out of the way. One of Railiance's goals is that initiating a new Railiance should be easy; this repo is where that claim is made testable.

Repository status: this repo previously carried a copied declaration identifying it as the S2 cluster runtime layer, duplicating railiance-cluster. That was wrong and has been corrected — see INTENT.md → History. Restructuring of the inherited content is in progress; expect S2-era material still present in ansible/, helm/, docs/ and wiki/ that has not yet been sorted into "bootstrap path" versus "belongs to S1/S2".

---

In Scope

• The newcomer path from bare VM to working Railiance (QUICKSTART.md)
• Prerequisite and ordering contracts between substrate, cluster, secrets, forge
• Bootstrap secret material: how it is introduced, and how it is retired once the real custody path (OpenBao, S3) exists
• The handoff point where the ordinary layers take over
• A rehearsable test that the bootstrap path still works

---

Out of Scope

• OS provisioning, hardening, server baseline → railiance-infra (S1)
• k3s, Helm, ingress, CNI, admission controllers, operators, kubeconfig management → railiance-cluster (S2)
• Shared stateful services: databases, cache, secrets, object storage → railiance-platform (S3)
• Ongoing operation of anything. After handoff this repo has no running role
• Duplicating layer content — this repo sequences layers, it does not own what they own

---

Relevant When

• Standing up a new Railiance from nothing
• Establishing or changing the ordering between substrate, cluster and secrets
• Resolving a bootstrap chicken-and-egg problem (needing a secret to fetch the code that manages secrets)
• Testing that the adoption path still works by raising a fresh Railiance

Not Relevant When

• Operating, upgrading, or troubleshooting an existing Railiance — that belongs to the layer that owns the concern
• Deploying a workload (that is rapp-* and S5)

---

Current State

• Status: repurposed, restructuring in progress
• The bootstrap intent is declared (INTENT.md, 2026-08-11); the inherited S2 content has not yet been sorted
• QUICKSTART.md is the existing seed of the newcomer path; a near-identical copy also exists in railiance-cluster and the two need consolidating
• install/ exists in railiance-cluster but not here, and is a candidate to move
• Open: whether the bootstrap path has ever been walked end to end from scratch

---

How It Fits

• Sequences: railiance-infra (S1) → railiance-cluster (S2) → railiance-platform (S3), and hands off once they can run themselves
• Downstream: everything, indirectly — this is the entry point
• Often used with: railiance-master (which owns the layer model this sequences), railiance-platform (which takes over secret custody after bootstrap material is retired)

---

Terminology

• Preferred terms: bootstrap path, ignition sequence, handoff point, bootstrap secret material
• Potentially confusing: "bootstrap" here means initiating a whole Railiance, not cluster bootstrap in the k3s sense (that is S2), and not ArgoCD app-of-apps bootstrapping (that is S3's argocd/bootstrap/)

---

Getting Oriented

• Start with: INTENT.md, then QUICKSTART.md
• Context: railiance-platform/ArchitectureBlueprint.md §4 records this repo's lineage and status
• Pre-conditions: one reachable virtual machine, and nothing else

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard. It does not contact the hub, alter workplan statuses, or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.

Local orientation brief policy — 2026-10-21

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index keep their existing source and staged-generation contracts.