diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..f8608ac
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,80 @@
+# Railiance Documentation
+
+Welcome to **Railiance** — an opinionated framework for Infrastructure-as-Code.  
+Think of it as *Rails for Ops*: convention over configuration, productivity first, reproducible everywhere.
+
+---
+
+## 🚀 What is Railiance?
+
+Railiance is the **self-reliant infrastructure bootstrap** for Coulomb and beyond.  
+From two bare Linux servers, a Git repo, and valid credentials, you can rebuild a full Kubernetes-based environment with:
+
+- **Automated provisioning** (Ansible, Helm, k3s)  
+- **Git-driven state** (ArgoCD / Flux)  
+- **AI-ready automation** with OODA loop (Observe, Orient, Decide, Act)  
+- **End-to-end reproducibility** — no hidden steps, no snowflake servers  
+
+---
+
+## 🌱 Core Principles
+
+1. **Convention over configuration**  
+   Opinionated defaults remove friction.  
+
+2. **Don’t repeat yourself (DRY)**  
+   Single source of truth in Git, reused everywhere.  
+
+3. **Automated OODA**  
+   - *Observe*: collect telemetry.  
+   - *Orient*: AI interprets state.  
+   - *Decide*: human reviews & authorizes.  
+   - *Act*: automation applies changes.  
+
+4. **Self-Reliance**  
+   Everything can be rebuilt from scratch, with no external dependencies beyond Git + credentials.  
+
+5. **Calm Ops**  
+   Systems should be simple, resilient, and predictable.  
+
+---
+
+## 📂 Repo Layout
+
+- `ansible/` — bootstrap playbooks (OS setup, k3s install, etc.)  
+- `helm/` — Helm charts for services  
+- `k8s/` — raw manifests & overlays  
+- `tests/` — automated validation of infra steps  
+- `docs/` — documentation & contributor guides  
+- `tools/` — helper scripts (e.g. repo bootstrap)  
+
+---
+
+## 🛠 Getting Started
+
+1. **Clone the repo**  
+   ```bash
+   git clone <your-gitea-url>/railiance-bootstrap.git
+   cd railiance-bootstrap
+   
+2. **Prepare your config**
+    Edit ~/.railiance_gitea.conf with your Gitea URL, user, and token.
+    (Never commit this file!)
+
+3. **Run bootstrap**
+   Use the playbooks in ansible/ to turn a bare Ubuntu server into a Kubernetes host.
+
+4. **Deploy services**
+   Install baseline services via Helm from the helm/ directory.
+
+## 👥 Contributing
+
+See CONTRIBUTING.md for rules, coding style, and workflow.
+
+## 🌍 Vision
+
+Railiance is more than infra scripts: it’s the foundation of self-empowering infrastructure,
+where humans and AI agents collaborate to manage systems with trust, clarity, and calmness.
+
+From bare metal to resilient clusters, in one repo.
+