Clarify cluster boundary for rail-kubernetes

docs/README.md

@@ -1,77 +1,30 @@
-# Railiance Documentation
+# railiance-cluster Docs
 
-Welcome to **Railiance** — an opinionated framework for Infrastructure-as-Code.  
-Think of it as *Rails for Ops*: convention over configuration, productivity first, reproducible everywhere.
+This directory mixes two kinds of material:
 
----
+- stable S2 cluster-substrate docs that belong in `railiance-cluster`
+- transitional workload-contract docs that are temporarily hosted here until
+  `rail-kubernetes` exists
 
-## 🚀 What is Railiance?
+Use the sections below to keep those concerns separate.
 
-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:
+## S2 Substrate Docs
 
-- **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  
+- [Operator runbook](operator-runbook.md)
+- [Backup and restore](backup-restore.md)
+- [Kubeconfig](kubeconfig.md)
+- [First host](first_host.md)
 
----
+## Published Boundary Docs
 
-## 🌱 Core Principles
+- [rail-kubernetes extraction map](rail-kubernetes-extraction-map.md)
+- [rail-kubernetes substrate profile](rail-kubernetes-substrate-profile.md)
 
-1. **Convention over configuration**  
-   Opinionated defaults remove friction.  
+## Transitional Workload-Contract Docs
 
-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-cluster.git
-   cd railiance-cluster
-   
-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.
-
-## Incidents
-
-- [2026-03-10 — pgpool CrashLoopBackOff on PostgreSQL HA failover](incidents/2026-03-10-pgpool-missing-secret.md)
-
-## Operations
+These docs describe the generic workload-on-Kubernetes contract. They are still
+hosted in this repo for compatibility, but they are targeted for extraction to
+future `rail-kubernetes`.
 
 - [Deployment lifecycle](deployment-lifecycle.md)
 - [Railiance app.toml contract](app-toml-contract.md)
@@ -81,13 +34,6 @@ From two bare Linux servers, a Git repo, and valid credentials, you can rebuild
 - [Promote, rollback, and onboarding](promote-rollback-onboarding.md)
 - [Railiance run command](railiance-run-command.md)
 
-## 👥 Contributing
+## Incidents
 
-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.
+- [2026-03-10 - pgpool CrashLoopBackOff on PostgreSQL HA failover](incidents/2026-03-10-pgpool-missing-secret.md)