railiance-bootstrap/INTENT.md

# INTENT

> This file captures **why this repository exists**,
> the **direction it is moving toward**, and
> the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of current implementation.

---

## One-liner

**The bootstrap path — turning a single bare virtual machine into a working Railiance, so that standing up a new Railiance is a repeatable procedure rather than an act of memory.**

---

## Why This Exists

Railiance's layers each describe how to operate a system that **already
exists**. S1 converges a substrate, S2 runs a cluster on it, S3 provides shared
services, and so on. Every one of them assumes the thing beneath it is already
there.

Nothing owns the first step: *you have one virtual machine and an intention —
now what?*

Without a bootstrap path:

* standing up a new Railiance depends on the memory of whoever did it last,
* the ordering between substrate, cluster, secrets, and forge is rediscovered
  each time,
* the chicken-and-egg problems (secrets needed to fetch the code that manages
  secrets) are solved ad hoc and differently each time,
* and "Railiance is easy to adopt" stays an aspiration nobody can test.

This repo exists so that a new Railiance can be **initiated from nothing**, by
someone who was not present when the first one was built.

---

## The Mission

> *Where we are going.*

To become the **canonical entry point into Railiance** — the one repository a
newcomer clones to turn a bare machine into a Railiance that can then manage
itself through the ordinary layers.

This means:

* The path from **one VM to a working Railiance** is a documented, runnable
  sequence
* **Ordering and prerequisites** between layers are explicit, not folklore
* Bootstrap **chicken-and-egg problems** are named and solved deliberately
* The procedure is **testable** — a new Railiance can be raised from scratch to
  prove the path still works
* Once bootstrapped, the system **hands off** to the ordinary layers and this
  repo steps out of the way

---

## Core Principles

### 1. From Nothing, Repeatably

The path assumes no pre-existing Railiance, no prepared secrets, and no
institutional memory. If a step depends on something that already exists, that
dependency is stated.

### 2. Hand Off, Do Not Hold

This repo raises a Railiance and then yields. Ongoing operation belongs to S1–S5.
Anything this repo keeps operating is a boundary violation.

### 3. The Path Is Tested by Walking It

A bootstrap procedure that has not been run from scratch recently is a
hypothesis. Proving it means raising a new Railiance, not reviewing the
document.

### 4. Honest About Manual Steps

Some bootstrap steps genuinely require a human — provisioning a machine,
entering a root credential. These are named as such rather than hidden behind
automation that pretends otherwise.

### 5. Adoption Is the Point

Ease of initiation is a Railiance goal, not a convenience. A Railiance that only
its author can stand up is not a framework.

---

## What This Is (Conceptually)

The **ignition sequence** for a Railiance:

* the newcomer quickstart and its prerequisites
* the ordering contract between substrate, cluster, secrets, and forge
* bootstrap secret material handling, and how it is replaced by the real custody
  path once one exists
* the handoff point where the ordinary layers take over
* a test that the whole path still works

---

## What This Is Not

* **Not the cluster runtime.** k3s, Helm, ingress, CNI, operators and kubeconfig
  management belong to `railiance-cluster` (S2). This repo previously declared
  itself S2 — that was a copied declaration, not an intent.
* **Not the infrastructure substrate.** OS provisioning, hardening and baseline
  belong to `railiance-infra` (S1).
* **Not a second home for layer content.** It sequences the layers; it does not
  duplicate what they own.
* **Not an ongoing operations repo.** After handoff, it has no running role.

---

## Direction of Evolution

This layer is expected to evolve toward:

* A **single documented path** from bare VM to working Railiance
* Explicit **prerequisite and ordering** contracts with S1 and S2
* Deliberate handling of **bootstrap secret material** and its retirement
* A **rehearsable** bootstrap — proven by raising a fresh Railiance, not by review
* Reduced manual steps over time, with the remaining ones **named honestly**
* Eventually, bootstrapping onto **substrates other than the current one**
  without changing the model

---

## History

This repository previously carried a copied declaration identifying it as the
S2 cluster runtime layer — identical in intent to `railiance-cluster`, with
which it shares no git history but nearly all of its content. It was one of four
repos (`bootstrap`, `cluster`, `hosts`, `infra`) created by copying working
trees as the S1/S2 layering idea emerged.

That declaration was wrong. The repository's own `QUICKSTART.md` — *"set up your
very first Railiance host"* — describes what this repo is actually for, and this
INTENT now states it.

See `railiance-platform/ArchitectureBlueprint.md` §4 for the full lineage and
`history/2026-08-11-railiance-architecture-in-aspiration.md` for the assessment.

---

## Guiding Question

> *Could someone who was not there raise a new Railiance from this?*