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