Bootstrap the first rail-kubernetes repo

docs/README.md

@@ -0,0 +1,4 @@
+# rail-kubernetes Docs
+
+- `wave-1-contract.md` — current rail contract and boundary summary
+- `source-import-plan.md` — source material and migration direction from existing repos

docs/source-import-plan.md

@@ -0,0 +1,40 @@
+# Source Import Plan
+
+## Purpose
+
+Record which reviewed source materials are expected to seed this repo.
+
+## First-Wave Imports
+
+Expected source documents from `railiance-cluster`:
+
+- `docs/deployment-lifecycle.md`
+- `docs/app-toml-contract.md`
+- `docs/overlay-repo-pattern.md`
+- `docs/canary-helm-template.md`
+- `docs/stage2-deploy-observe.md`
+- `docs/promote-rollback-onboarding.md`
+- `docs/railiance-run-command.md`
+
+Expected source assets from `railiance-cluster`:
+
+- `schemas/railiance-app.schema.json`
+- `examples/railiance/app.toml`
+- `tools/create_railiance_overlay_repo.sh`
+- `tools/cmd/railiance-run`
+- `tools/cmd/railiance-stage2`
+- `tools/cmd/railiance-stage3`
+
+## Deferred Migration Debt
+
+Do not import these into `rail-kubernetes` as part of wave 1:
+
+- workload-specific activity-core helper commands
+- workload-specific smoke or reconciliation helpers
+- cluster substrate operations
+- shared bootstrap helpers that still need a separate placement review
+
+## Rule
+
+Imports into this repo should preserve the boundary already reviewed in
+`railiance-master` and `railiance-cluster`.

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.