tegwick
b0177947dd
The generated index had drifted from the workplan files. The opt-in lets the pre-commit hook rebuild WORK-RECORDS.md in the same commit as the workplan it indexes. Assistant: grok Assistant-Session: 01a17f9d-fe9d-7d72-9a22-6304f1a2a790
133 lines
5.1 KiB
Markdown
133 lines
5.1 KiB
Markdown
# 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.
|