railiance-cluster/tools/README_tools.md

# 🌱 Railiance Tools — Directed Panspermia Model

Railiance bootstraps infrastructure in a way inspired by **directed panspermia** —  
the idea of life being intentionally seeded across the cosmos.  
Here, instead of biology, we seed **infrastructure-as-code** into blank environments.

---

## 🧬 Core Concepts

- **Parent Body** — an existing Railiance repo (the source of life).
- **Seed** — the minimal set of instructions/scripts to reproduce the repo in a new environment.
- **Spore** — a portable, bundled package of the Seed (self-contained, easy to transfer).
- **Target Environment** — a blank host (a sterile world waiting for life).
- **Biogenesis** — the process of unpacking a Spore and bootstrapping the environment.
- **Evolutionary Adaptation** — further provisioning, testing, and tuning specific to the host.

---

## 🛠️ Toolchain Overview

### `create_railiance_repo.sh`
- Creates a new Railiance repo in Gitea (under user or org).
- Acts like the *egg cell*: it defines the first container for life.

### `furnish_railiance_repo.sh`
- Idempotently sets up repo housekeeping files (LICENSE, README, .editorconfig, etc.).
- Brings the repo to a clean, opinionated state.
- Equivalent to providing the *genetic code*.

### `build_spore.sh`
- Packages the Seed into a **Spore bundle** (tar.gz).
- Includes creation/furnishing scripts, docs, and metadata.
- Like enclosing life into a *protective capsule* for travel.

### `seed_node.sh`
- Run on a blank host to unpack a Spore.
- Performs **Biogenesis**: installs prerequisites, clones the repo, and executes bootstrap steps.
- Like a *spore germinating* on a fertile planet.

---

## 🚀 Lifecycle

1. **Create** a repo with `create_railiance_repo.sh`.
2. **Furnish** it into a clean Railiance structure with `furnish_railiance_repo.sh`.
3. **Build** a distributable bundle with `build_spore.sh`.
4. **Seed** new environments with `seed_node.sh`.

---

## 🌍 Why Panspermia?

This model emphasizes:
- **Reproducibility**: every host can be bootstrapped identically from a Spore.
- **Federation**: Spores can be sent to many environments (different orgs, clusters, or even air-gapped hosts).
- **Resilience**: infrastructure survives and adapts, no matter the environment.
- **Storytelling**: by using biological metaphors, we keep the process intuitive and memorable.

---



### `railiance-stage3`
- Backs `bin/railiance promote` and `bin/railiance rollback`.
- Emits non-secret JSON plans/results for stable promotion and rollback.

### `railiance-stage2`
- Backs `bin/railiance deploy --stage 2` and `bin/railiance observe --stage 2`.
- Emits non-secret JSON plans/results for canary deployment and observation.

### `railiance-run`
- Executes Stage 1 local validation from `railiance/app.toml`.
- Emits a `railiance.run-result.v1` JSON result without command logs or secrets.

### `create_railiance_overlay_repo.sh`
- Scaffolds a local Railiance overlay repo for a third-party upstream app.
- Records upstream identity without vendoring upstream code.
- Generates `railiance/app.toml`, a stage-aware canary chart, stage values,
  tests, and runbooks.

✦ Railiance is not just code — it’s a way of letting infrastructure **colonize new worlds**.