Bootstrap the first rail-kubernetes repo

docs/wave-1-contract.md

@@ -0,0 +1,59 @@
+# Wave-1 Kubernetes Rail Contract
+
+## Purpose
+
+Summarize the initial contract `rail-kubernetes` owns in wave 1.
+
+This repo starts from already-reviewed source documents rather than inventing a
+new runtime model:
+
+- `railiance-master/docs/rail-kubernetes-boundary.md`
+- `railiance-cluster/docs/rail-kubernetes-extraction-map.md`
+- `railiance-cluster/docs/rail-kubernetes-substrate-profile.md`
+
+## What `rail-kubernetes` Owns
+
+Wave 1 assigns these concerns to the rail:
+
+- the generic workload-on-Kubernetes execution contract
+- the generic `railiance/app.toml` workload declaration surface
+- generic stage 1 / stage 2 / stage 3 lifecycle semantics
+- generic canary, observe, promote, and rollback behavior
+- generic wrapper and overlay guidance for workloads that still use the current
+  overlay pattern during migration
+
+## What Stays In `railiance-cluster`
+
+Wave 1 keeps these concerns in the S2 ownership repo:
+
+- k3s bootstrap and host-to-cluster installation
+- cluster backup, restore, smoke, and preflight operations
+- operator ownership for ingress, TLS, and other cluster-level components
+- cluster access delivery and kubeconfig handling
+- substrate-level safety rails
+
+## Published Substrate Assumptions
+
+Wave 1 `rail-kubernetes` may assume:
+
+- a Kubernetes API backed by k3s
+- Helm-based apply paths
+- operator-driven kubeconfig access
+- isolated canary exposure as the safe default
+- namespace creation during workload rollout
+
+Wave 1 `rail-kubernetes` must not assume:
+
+- guaranteed weighted routing
+- a generic workload RBAC model
+- a generic persistent-storage contract
+- a secret-delivery contract at the S2 layer
+
+## Migration Constraint
+
+Until the extraction is complete, `railiance-cluster` remains the compatibility
+surface for current operators.
+
+`rail-kubernetes` should become the durable home of the contract first. Only
+then should commands, docs, schemas, and helpers move here in a migration-safe
+sequence.