Establish Railiance architecture home

docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md

@@ -0,0 +1,64 @@
+# ADR-0002: Wave 1 `rail-kubernetes` Boundary
+
+Date: 2026-07-25
+Status: Accepted
+
+## Context
+
+Railiance wants `rail-*` repos to represent workload execution contracts rather
+than abstract naming ideas.
+
+Today, the concrete Kubernetes workload contract already exists, but it is
+embedded in `railiance-cluster`. That repo currently owns both:
+
+- the S2 Kubernetes substrate
+- and the generic workload lifecycle and tooling that run on top of it
+
+That mixed ownership is the main blocker to introducing the first real rail.
+
+## Decision
+
+Railiance will treat `rail-kubernetes` as the wave-1 base rail.
+
+The boundary is:
+
+- `railiance-cluster` owns the Kubernetes substrate and its prerequisites
+- `rail-kubernetes` owns the generic workload-on-Kubernetes execution contract
+
+Workload-specific helper flows currently living in `railiance-cluster` are
+temporary exceptions and must be rehomed rather than carried forward as part of
+the generic rail.
+
+## Consequences
+
+### Positive
+
+- The first real rail gains a concrete ownership boundary.
+- `railiance-cluster` can return to a clean S2 substrate identity.
+- Future rails such as `rail-knative` get a stable base boundary to extend from.
+- `rapp-*` repos gain a clearer execution-contract home for Kubernetes-managed
+  workloads.
+
+### Required Follow-On Work
+
+- Create the detailed `rail-kubernetes` boundary contract and migration map.
+- Split generic lifecycle docs, schema, examples, and Stage 1-3 tooling out of
+  `railiance-cluster`.
+- Leave a compatibility path so current users of the cluster repo are not
+  broken during the migration.
+- Rehome workload-specific helpers that do not belong in either boundary.
+
+### Constraints
+
+- `rail-kubernetes` must not take ownership of cluster bootstrap, operators, or
+  kubeconfig management.
+- `railiance-cluster` must not continue as the owner of generic workload
+  promotion semantics after the split.
+- `rail-knative` should follow this cleanup, not bypass it.
+
+## Notes
+
+This ADR does not require all current files to move immediately.
+
+It requires the ownership line to be explicit now, so practical repo separation
+can proceed without ambiguity.