Add rail-kubernetes compatibility shim

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`.