From 2acc06f466ed8e89349525c5d4b1ab5fd50b70fc Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Tue, 17 Mar 2026 23:11:38 +0100
Subject: [PATCH] docs: add SCOPE.md for rapid orientation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 SCOPE.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 SCOPE.md

diff --git a/SCOPE.md b/SCOPE.md
new file mode 100644
index 0000000..f612272
--- /dev/null
+++ b/SCOPE.md
@@ -0,0 +1,101 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+S2 Cluster Runtime layer of the Railiance OAS Stack — owns k3s installation, Helm, ingress, CNI, admission controllers, operators, and kubeconfig management.
+
+---
+
+## Core Idea
+
+Railiance is structured as five independent repos per OAS Stack layer. This repo is S2. It installs and configures the Kubernetes cluster runtime: k3s, Helm, ingress controller, CNI plugin, cluster addons and operators. S1 (OS) must be converged before S2 can run. S2 explicitly does not own platform services (PostgreSQL, caches) — those are S3.
+
+---
+
+## In Scope
+
+- k3s installation and baseline configuration
+- Helm chart management
+- Ingress controller, CNI plugin
+- Admission controllers and cluster operators
+- Cluster addons (cert-manager, etc.)
+- kubeconfig management and access
+- Smoke tests to validate cluster health
+
+---
+
+## Out of Scope (per ADR-003)
+
+- OS security hardening, SSH, firewall → railiance-infra (S1)
+- Platform services (PostgreSQL HA, Valkey, object storage) → railiance-platform (S3)
+- CI/CD and developer tooling → railiance-enablement (S4)
+- Application deployments → railiance-apps (S5)
+- No re-configuration of S1 concerns from this repo
+
+---
+
+## Relevant When
+
+- Setting up or maintaining the Kubernetes cluster runtime
+- Installing or updating cluster-level operators and addons
+- Diagnosing cluster health (smoke tests)
+- k3s upgrades or kubeconfig rotation
+
+---
+
+## Not Relevant When
+
+- OS-level work (use railiance-infra)
+- Platform service configuration (use railiance-platform)
+- Application deployments (use railiance-apps)
+
+---
+
+## Current State
+
+- Status: active / mostly complete
+- Implementation: k3s baseline complete (RAIL-BS-WP-0002); active bug fixes (RAIL-BS-WP-0003 pgpool HA failover); safety net tooling in progress (RAIL-BS-WP-0004)
+- Stability: high for k3s baseline; active improvements ongoing
+- Usage: core Kubernetes runtime for all Railiance deployments; runs on HostEurope server
+
+---
+
+## How It Fits
+
+- Upstream dependencies: railiance-infra (S1) — OS must be converged and verified
+- Downstream consumers: railiance-platform (S3), railiance-enablement (S4), railiance-apps (S5)
+- Often used with: railiance-platform (next layer to configure after cluster is up)
+
+---
+
+## Terminology
+
+- Preferred terms: OAS Stack Level S2, smoke test, pre-condition chain, boundary rule
+- Potentially confusing terms: cluster runtime ≠ platform services; Gitea and databases are NOT S2 concerns
+
+---
+
+## Related / Overlapping Repositories
+
+- `railiance-infra` (S1) — must be converged before this layer runs
+- `railiance-platform` (S3) — consumes the cluster runtime provided by S2
+
+---
+
+## Getting Oriented
+
+- Start with: `CLAUDE.md` (session protocol, remote execution via SSH tunnel), `README.md`
+- Key files / directories: `workplans/` (4 active), `.sops.yaml` (secret encryption)
+- Entry points: `Makefile` targets; remote work requires SSH tunnel to State Hub
+
+---
+
+## Notes
+
+Designed for remote execution from HostEurope (92.205.130.254). Requires SSH reverse tunnel: `ssh -R 8000:127.0.0.1:8000 <user>@remote`.