# Cluster Compatibility Handoff

## Purpose

Define the migration-window handoff between `railiance-cluster` and
`rail-kubernetes` for the generic workload lifecycle surface.

Wave 1 makes `rail-kubernetes` the durable owner of the generic Kubernetes
rail contract. `railiance-cluster` remains the S2 substrate owner and keeps a
thin compatibility shim so current operators do not need a flag day.

## Canonical Command Owner

Use `rail-kubernetes/bin/railiance` as the canonical entrypoint for these
generic rail commands:

- `create-overlay`
- `run`
- `deploy`
- `observe`
- `promote`
- `rollback`

New behavior, docs, and fixes for those commands should land in
`rail-kubernetes` first.

## Cluster-Side Compatibility Shim

During the migration window, `railiance-cluster/bin/railiance` keeps the same
six command names but resolves them in this order:

1. If `RAILIANCE_RAIL_KUBERNETES_BIN` is set, use that executable path.
2. Else, if a sibling checkout exists at `../rail-kubernetes/bin/railiance`,
   delegate to it.
3. Else, fall back to the temporary compatibility copies still present in
   `railiance-cluster`.

If `RAILIANCE_RAIL_KUBERNETES_BIN` is set but not executable, the cluster-side
shim fails closed rather than silently using a different path.

This keeps existing `railiance-cluster/bin/railiance ...` invocations working
while shifting canonical ownership to `rail-kubernetes`.

## What Still Stays Outside The Handoff

The compatibility shim does not expand the rail boundary.

Still retained in `railiance-cluster` as S2 substrate operations:

- `backup`
- `preflight`

Still present in `railiance-cluster` but outside the `rail-kubernetes` handoff:

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

Those commands need their own long-term placement review; they are not part of
the generic rail contract.

## Operator Migration Path

Operators can move without changing command arguments:

1. Clone `rail-kubernetes` alongside `railiance-cluster`, or set
   `RAILIANCE_RAIL_KUBERNETES_BIN` to the preferred checkout.
2. Continue using `railiance-cluster/bin/railiance` during the migration window
   if needed; it will delegate when the rail repo is available.
3. Prefer `rail-kubernetes/docs/` as the canonical documentation surface for
   the six generic lifecycle commands.

## Exit Condition

The migration window can end once current operator entrypoints and automation
no longer depend on the cluster-side fallback copies.