Clarify cluster boundary for rail-kubernetes

README.md

@@ -1,60 +1,54 @@
-# Railiance Cluster
+# railiance-cluster
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Opinionated Infrastructure-as-Code framework for reproducible, self-reliant systems.
+S2 cluster runtime home for Railiance: Kubernetes substrate ownership, cluster
+operators, kubeconfig delivery, backup/preflight safety rails, and published
+cluster facts that downstream workload rails depend on.
 
-Railiance is an opinionated **Infrastructure-as-Code framework** —  
-think *Rails for Ops*: convention over configuration, reproducibility first.
+This repo is the Kubernetes substrate owner, not the long-term home for the
+generic workload-on-Kubernetes contract. The staged workload lifecycle,
+`railiance/app.toml`, and overlay/wrapper scaffolding still live here as a
+compatibility layer and are being prepared for extraction to a future
+`rail-kubernetes` repo.
 
-This repo (`railiance-cluster`) is the **cluster runtime entry point**:  
-from two bare Linux servers, a Git repo, and credentials, you can rebuild  
-a fully automated Kubernetes-based environment.
+## Current Boundary
 
----
+- S2-owned here: k3s bootstrap, Helm and kubeconfig access, cluster-level
+  backup/preflight, smoke checks, and published substrate expectations.
+- Transitional here only: generic Stage 1/2/3 workload lifecycle semantics,
+  `railiance/app.toml`, canary/promotion CLI commands, and overlay scaffolding.
+- Reviewed move map:
+  [docs/rail-kubernetes-extraction-map.md](docs/rail-kubernetes-extraction-map.md)
+- Published substrate profile:
+  [docs/rail-kubernetes-substrate-profile.md](docs/rail-kubernetes-substrate-profile.md)
 
-## 🚀 Quick Start
+## Quick Start
 
-1. **Clone this repo**
+1. Clone this repo.
    ```bash
    git clone <your-gitea-url>/railiance-cluster.git
    cd railiance-cluster
    ```
+2. Configure Gitea access in `~/.railiance_gitea.conf`.
+3. Bootstrap a host with the Ansible playbooks in `ansible/`.
+4. Validate the cluster substrate with the documented smoke/preflight targets.
 
-2. **Configure Gitea access**  
-   Edit `~/.railiance_gitea.conf` with your server URL, username, and token.  
-   *(Never commit this file!)*
+## Repo Structure
 
-3. **Bootstrap a host**  
-   Run the Ansible playbooks in `ansible/` to set up k3s, Helm, kubectl.  
+- `ansible/` - S2 bootstrap playbooks
+- `helm/` - retained cluster-side helper manifests
+- `tests/` - cluster validation and HA smoke checks
+- `docs/` - S2 substrate docs plus transitional rail-kubernetes specs
+- `tools/` - S2 operations plus compatibility tooling that is being split out
+- `workplans/` - repo-local cluster work records
 
-4. **Deploy baseline services**  
-   Use `helm/` charts to roll out essential services (GitOps, monitoring, etc.).  
+## Key Docs
 
-5. **Validate**  
-   Check the automated tests in `tests/` to confirm infra health.  
+- [SCOPE.md](SCOPE.md)
+- [docs/README.md](docs/README.md)
+- [docs/rail-kubernetes-extraction-map.md](docs/rail-kubernetes-extraction-map.md)
+- [docs/rail-kubernetes-substrate-profile.md](docs/rail-kubernetes-substrate-profile.md)
 
----
+## Contributing
 
-## 📂 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.*
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).