Add rail-kubernetes compatibility shim

docs/README.md

@@ -19,12 +19,14 @@ Use the sections below to keep those concerns separate.
 
 - [rail-kubernetes extraction map](rail-kubernetes-extraction-map.md)
 - [rail-kubernetes substrate profile](rail-kubernetes-substrate-profile.md)
+- [rail-kubernetes compatibility shim](rail-kubernetes-compatibility-shim.md)
 
 ## Transitional Workload-Contract Docs
 
 These docs describe the generic workload-on-Kubernetes contract. They are still
-hosted in this repo for compatibility, but they are targeted for extraction to
-future `rail-kubernetes`.
+hosted in this repo for compatibility, but canonical ownership now lives in
+`rail-kubernetes` and the cluster repo should keep only temporary copies or
+pointer docs during the migration window.
 
 - [Deployment lifecycle](deployment-lifecycle.md)
 - [Railiance app.toml contract](app-toml-contract.md)

docs/rail-kubernetes-compatibility-shim.md

@@ -0,0 +1,45 @@
+# rail-kubernetes Compatibility Shim
+
+## Purpose
+
+Record the migration-window behavior that keeps current
+`railiance-cluster/bin/railiance` users working while canonical ownership of
+the generic workload lifecycle commands moves to `rail-kubernetes`.
+
+## Delegated Commands
+
+The cluster-side shim covers only these generic rail commands:
+
+- `create-overlay`
+- `run`
+- `deploy`
+- `observe`
+- `promote`
+- `rollback`
+
+For those commands, `railiance-cluster/bin/railiance` now delegates to
+`rail-kubernetes/bin/railiance` when a configured or sibling checkout exists.
+
+Resolution order:
+
+1. `RAILIANCE_RAIL_KUBERNETES_BIN`
+2. sibling checkout at `../rail-kubernetes/bin/railiance`
+3. temporary local compatibility copy in `railiance-cluster`
+
+If `RAILIANCE_RAIL_KUBERNETES_BIN` is set but not executable, the shim fails
+closed.
+
+## Commands Not Covered
+
+These remain outside the handoff:
+
+- S2 substrate commands such as `backup` and `preflight`
+- shared bootstrap helpers such as `doctor`, `plan-host`, `cloudinit`,
+  `init-repo`, `build-spore`, `seed-local`, and `checklist`
+- workload-specific helpers such as `deploy-triage-robustness` and
+  `admin-sync-smoke`
+
+## Canonical Home
+
+The canonical rail-side migration contract lives in the sibling
+`rail-kubernetes` repo at `docs/cluster-compatibility-handoff.md`.