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