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.