From 038adef94acb5d244c447f3f9513a15fc7765f57 Mon Sep 17 00:00:00 2001
From: Bernd Worsch <bernd.worsch@gmail.com>
Date: Fri, 12 Sep 2025 02:36:45 +0200
Subject: [PATCH] docs: update root README with quick start and structure

---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 5f3c6ed..5fbceb9 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,57 @@
-# railiance-bootstrap
+# Railiance Bootstrap
 
-**Railiance Bootstrap** — opinionated, reproducible IaC to rebuild Coulomb infra from scratch.
+Railiance is an opinionated **Infrastructure-as-Code framework** —  
+think *Rails for Ops*: convention over configuration, reproducibility first.
 
-## Goals
-- Two Linux machines + this Git repo + credentials ⇒ full rebuild
-- GitOps-first with ArgoCD/Flux
-- OODA (Observe→Orient→Decide→Act) encoded as pipelines
-- Tests define success at every step
+This repo (`railiance-bootstrap`) is the **entry point**:  
+from two bare Linux servers, a Git repo, and credentials, you can rebuild  
+a fully automated Kubernetes-based environment.
 
-## Layout
-```
-ansible/  # host bootstrap
-helm/     # charts & values
-k8s/      # raw manifests/CRDs
-tests/    # expectation tests (bash/py)
-docs/     # operator notes, OODA SOPs
-```
+---
+
+## 🚀 Quick Start
+
+1. **Clone this repo**
+   ```bash
+   git clone <your-gitea-url>/railiance-bootstrap.git
+   cd railiance-bootstrap
+   ```
+
+2. **Configure Gitea access**  
+   Edit `~/.railiance_gitea.conf` with your server URL, username, and token.  
+   *(Never commit this file!)*
+
+3. **Bootstrap a host**  
+   Run the Ansible playbooks in `ansible/` to set up k3s, Helm, kubectl.  
+
+4. **Deploy baseline services**  
+   Use `helm/` charts to roll out essential services (GitOps, monitoring, etc.).  
+
+5. **Validate**  
+   Check the automated tests in `tests/` to confirm infra health.  
+
+---
+
+## 📂 Repo Structure
+
+- `ansible/` — Playbooks for provisioning  
+- `helm/` — Opinionated Helm charts  
+- `k8s/` — Kubernetes manifests  
+- `tests/` — Automated validation  
+- `docs/` — Documentation (see [docs/README.md](./docs/README.md))  
+- `tools/` — Helper scripts (e.g. `create_railiance_repo.sh`)  
+
+---
+
+## 🤝 Contributing
+
+See [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md).  
+
+---
+
+## 🌍 Vision
+
+Railiance aims for **self-reliant infrastructure**:  
+automation you can rebuild from scratch, with calmness and clarity.  
+
+> *From bare metal to resilient clusters — in one repo.*