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?