Finish rail-kubernetes bootstrap handoff

docs/README.md

@@ -8,5 +8,6 @@
 - `promote-rollback-onboarding.md` — representative lifecycle command path
 - `railiance-run-command.md` — stage 1 command behavior contract
 - `create-overlay-command.md` — overlay scaffolder behavior contract
+- `cluster-compatibility-handoff.md` — migration-window handoff from `railiance-cluster`
 - `wave-1-contract.md` — current rail contract and boundary summary
 - `source-import-plan.md` — source material and migration direction from existing repos

docs/cluster-compatibility-handoff.md

@@ -0,0 +1,77 @@
+# 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.

docs/wave-1-contract.md

@@ -54,6 +54,13 @@ Wave 1 `rail-kubernetes` must not assume:
 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.
+The current migration-window handoff is:
+
+- `rail-kubernetes/bin/railiance` is the canonical owner for the six generic
+  lifecycle commands;
+- `railiance-cluster/bin/railiance` keeps those command names as a thin
+  delegation shim with a temporary local fallback;
+- retained S2 operations and non-rail helper debt stay outside this handoff.
+
+See `docs/cluster-compatibility-handoff.md` for the command-resolution path and
+operator migration steps.